{ "components": { "parameters": {}, "schemas": {}, "securitySchemes": { "bearerAuth": { "bearerFormat": "spk_...", "description": "API key in the form `Bearer spk_`. Mint a key at /app/settings/api-keys; the secret is shown once and never again.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Hand-designed REST surface for Spirby. See docs/api-surface.md for the canonical endpoint inventory.", "title": "Spirby API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/boards": { "get": { "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": {}, "type": "array" }, "nextCursor": { "type": ["string", "null"] } }, "required": ["data", "nextCursor"], "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List boards in the caller’s organization", "tags": ["boards"] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "maxLength": 500, "type": "string" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "slug": { "maxLength": 60, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "type": "string" } }, "required": ["name"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a board", "tags": ["boards"] } }, "/v1/boards/{boardId}": { "delete": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "confirmName": { "minLength": 1, "type": "string" } }, "required": ["confirmName"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a board (must be empty)", "tags": ["boards"] }, "get": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Read a single board", "tags": ["boards"] }, "patch": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "description": { "maxLength": 500, "type": "string" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "showChangelog": { "type": "boolean" }, "showRoadmap": { "type": "boolean" }, "slug": { "maxLength": 60, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update a board", "tags": ["boards"] } }, "/v1/boards/{boardId}/changelog": { "get": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": ["all", "draft", "published"], "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": {}, "type": "array" }, "nextCursor": { "type": ["string", "null"] } }, "required": ["data", "nextCursor"], "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List changelog entries on a board", "tags": ["changelog"] }, "post": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "properties": { "json": {}, "text": { "default": "", "maxLength": 50000, "type": "string" } }, "type": "object" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" }, "version": { "maxLength": 40, "minLength": 1, "type": "string" } }, "required": ["title"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a changelog draft", "tags": ["changelog"] } }, "/v1/boards/{boardId}/posts": { "get": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "sort", "required": false, "schema": { "enum": ["most_voted", "newest", "recently_active", "relevance"], "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "anyOf": [ { "enum": [ "open", "under_review", "planned", "in_progress", "shipped", "declined", "duplicate" ], "type": "string" }, { "items": { "enum": [ "open", "under_review", "planned", "in_progress", "shipped", "declined", "duplicate" ], "type": "string" }, "minItems": 1, "type": "array" } ] } }, { "in": "query", "name": "tagIds", "required": false, "schema": { "anyOf": [ { "minLength": 1, "type": "string" }, { "items": { "minLength": 1, "type": "string" }, "minItems": 1, "type": "array" } ] } }, { "in": "query", "name": "query", "required": false, "schema": { "maxLength": 200, "minLength": 1, "type": "string" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": {}, "type": "array" }, "nextCursor": { "type": ["string", "null"] } }, "required": ["data", "nextCursor"], "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List posts on a board", "tags": ["posts"] }, "post": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "properties": { "json": {}, "text": { "default": "", "maxLength": 50000, "type": "string" } }, "type": "object" }, "tagIds": { "items": { "minLength": 1, "type": "string" }, "maxItems": 3, "type": "array" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" } }, "required": ["title"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a post on a board", "tags": ["posts"] } }, "/v1/boards/{boardId}/tags": { "get": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List tags on a board", "tags": ["tags"] }, "post": { "parameters": [ { "in": "path", "name": "boardId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "name": { "maxLength": 40, "minLength": 1, "type": "string" } }, "required": ["name"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a tag on a board", "tags": ["tags"] } }, "/v1/changelog/{entryId}": { "delete": { "parameters": [ { "in": "path", "name": "entryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Soft-delete a changelog entry", "tags": ["changelog"] }, "get": { "parameters": [ { "in": "path", "name": "entryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Read a single changelog entry", "tags": ["changelog"] }, "patch": { "parameters": [ { "in": "path", "name": "entryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "properties": { "json": {}, "text": { "default": "", "maxLength": 50000, "type": "string" } }, "type": "object" }, "publishedAt": { "format": "date-time", "type": ["string", "null"] }, "slug": { "maxLength": 80, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "type": "string" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" }, "version": { "maxLength": 40, "minLength": 1, "type": ["string", "null"] } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Edit a changelog entry; setting publishedAt to a future ISO schedules it", "tags": ["changelog"] } }, "/v1/changelog/{entryId}/linked-posts": { "put": { "parameters": [ { "in": "path", "name": "entryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "postIds": { "items": { "minLength": 1, "type": "string" }, "maxItems": 200, "type": "array" } }, "required": ["postIds"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replace the linked-posts set for a changelog entry", "tags": ["changelog"] } }, "/v1/changelog/{entryId}/publish": { "post": { "parameters": [ { "in": "path", "name": "entryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Publish a draft (idempotent on already-published)", "tags": ["changelog"] } }, "/v1/changelog/{entryId}/unpublish": { "post": { "parameters": [ { "in": "path", "name": "entryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Revert a published entry to draft", "tags": ["changelog"] } }, "/v1/comments/{commentId}": { "delete": { "parameters": [ { "in": "path", "name": "commentId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Soft-delete (tombstone) a comment", "tags": ["comments"] }, "patch": { "parameters": [ { "in": "path", "name": "commentId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "properties": { "json": {}, "text": { "maxLength": 50000, "minLength": 1, "type": "string" } }, "required": ["text"], "type": "object" } }, "required": ["body"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Edit a comment within the edit window", "tags": ["comments"] } }, "/v1/health": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [], "summary": "Liveness probe", "tags": ["system"] } }, "/v1/members": { "get": { "parameters": [ { "in": "query", "name": "cursor", "required": false, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": {}, "type": "array" }, "nextCursor": { "type": ["string", "null"] } }, "required": ["data", "nextCursor"], "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List members of the caller’s organization", "tags": ["members"] } }, "/v1/posts/{postId}": { "delete": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Soft-delete a post", "tags": ["posts"] }, "get": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Read a single post (with tags + merge/shipped metadata)", "tags": ["posts"] }, "patch": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "properties": { "json": {}, "text": { "default": "", "maxLength": 50000, "type": "string" } }, "type": "object" }, "hideFromRoadmap": { "type": "boolean" }, "slug": { "maxLength": 80, "minLength": 1, "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "type": "string" }, "status": { "enum": [ "open", "under_review", "planned", "in_progress", "shipped", "declined", "duplicate" ], "type": "string" }, "tagIds": { "items": { "minLength": 1, "type": "string" }, "maxItems": 3, "type": "array" }, "title": { "maxLength": 200, "minLength": 1, "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update a post", "tags": ["posts"] } }, "/v1/posts/{postId}/comments": { "get": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List comments on a post (threaded)", "tags": ["comments"] }, "post": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "body": { "properties": { "json": {}, "text": { "maxLength": 50000, "minLength": 1, "type": "string" } }, "required": ["text"], "type": "object" }, "parentId": { "minLength": 1, "type": "string" } }, "required": ["body"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Create a comment (top-level or one-level reply)", "tags": ["comments"] } }, "/v1/posts/{postId}/merge": { "post": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "sourceIds": { "items": { "minLength": 1, "type": "string" }, "maxItems": 20, "minItems": 1, "type": "array" } }, "required": ["sourceIds"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Merge other posts into this one (action endpoint)", "tags": ["posts"] } }, "/v1/posts/{postId}/votes": { "delete": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Retract a vote on a post (idempotent)", "tags": ["votes"] }, "post": { "parameters": [ { "in": "path", "name": "postId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Cast a vote on a post (idempotent)", "tags": ["votes"] } }, "/v1/tags/{tagId}": { "delete": { "parameters": [ { "in": "path", "name": "tagId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a tag", "tags": ["tags"] }, "patch": { "parameters": [ { "in": "path", "name": "tagId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "color": { "pattern": "^#[0-9a-fA-F]{6}$", "type": ["string", "null"] }, "name": { "maxLength": 40, "minLength": 1, "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Rename or recolor a tag", "tags": ["tags"] } }, "/v1/webhooks": { "get": { "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List the org’s webhooks", "tags": ["webhooks"] }, "post": { "requestBody": { "content": { "application/json": { "schema": { "properties": { "events": { "items": { "enum": [ "post.created", "post.status_changed", "vote.created", "comment.created", "changelog.published" ], "type": "string" }, "minItems": 1, "type": "array" }, "url": { "maxLength": 2048, "minLength": 1, "type": "string" } }, "required": ["url", "events"], "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Register a webhook (secret returned exactly once)", "tags": ["webhooks"] } }, "/v1/webhooks/{webhookId}": { "delete": { "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Delete a webhook", "tags": ["webhooks"] }, "get": { "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Read a single webhook (no secret)", "tags": ["webhooks"] }, "patch": { "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "properties": { "enabled": { "type": "boolean" }, "events": { "items": { "enum": [ "post.created", "post.status_changed", "vote.created", "comment.created", "changelog.published" ], "type": "string" }, "minItems": 1, "type": "array" }, "url": { "maxLength": 2048, "minLength": 1, "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Update a webhook (toggle enabled, change url or events)", "tags": ["webhooks"] } }, "/v1/webhooks/{webhookId}/deliveries": { "get": { "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "exclusiveMinimum": 0, "maximum": 200, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "List recent delivery attempts for a webhook (newest first)", "tags": ["webhooks"] } }, "/v1/webhooks/{webhookId}/deliveries/{deliveryId}/replay": { "post": { "parameters": [ { "in": "path", "name": "webhookId", "required": true, "schema": { "minLength": 1, "type": "string" } }, { "in": "path", "name": "deliveryId", "required": true, "schema": { "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": {} }, "type": "object" } } }, "description": "Successful response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Missing or invalid API key" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Scope insufficient (ERR_SCOPE_INSUFFICIENT) or org in readonly billing state (ERR_FORBIDDEN)" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Validation failed" }, "429": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Rate limit exceeded" }, "500": { "content": { "application/json": { "schema": { "properties": { "error": { "properties": { "code": { "type": "string" }, "details": { "additionalProperties": {}, "type": "object" }, "message": { "type": "string" } }, "required": ["code", "message"], "type": "object" } }, "required": ["error"], "type": "object" } } }, "description": "Internal error" } }, "security": [ { "bearerAuth": [] } ], "summary": "Replay a previously-failed delivery (action endpoint)", "tags": ["webhooks"] } } }, "servers": [ { "description": "Production", "url": "https://api.spirby.com" } ], "webhooks": {} }