{"openapi": "3.1.0", "info": {"title": "HeedPost API", "version": "1.0.0", "description": "The public REST API. One key, one workspace: the key names the workspace, so every request goes to the same host. Send it as `Authorization: Bearer hp_live_...`."}, "paths": {"/v1/boards": {"get": {"operationId": "apps_api_public_routers_list_boards", "summary": "List boards", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Every board this key can see, in the workspace's own order.", "tags": ["boards"], "security": [{"KeyAuth": []}]}, "post": {"operationId": "apps_api_public_routers_create_board", "summary": "Create a board", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Payment Required", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Make a board. The slug is its address, and every link to the board is\nbuilt from it. Choose it here, and change it later with its own endpoint.", "tags": ["boards"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/posts": {"get": {"operationId": "apps_api_public_routers_list_posts", "summary": "List posts", "parameters": [{"in": "query", "name": "board", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Board"}, "required": false}, {"in": "query", "name": "status", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Status"}, "required": false}, {"in": "query", "name": "kind", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Kind"}, "required": false}, {"in": "query", "name": "q", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Q"}, "required": false}, {"in": "query", "name": "roadmap", "schema": {"default": false, "title": "Roadmap", "type": "boolean"}, "required": false}, {"in": "query", "name": "user_segment", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "User Segment"}, "required": false}, {"in": "query", "name": "user_segment_label", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "User Segment Label"}, "required": false}, {"in": "query", "name": "value_min", "schema": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Value Min"}, "required": false}, {"in": "query", "name": "sort", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Sort"}, "required": false}, {"in": "query", "name": "limit", "schema": {"default": 25, "title": "Limit", "type": "integer"}, "required": false}, {"in": "query", "name": "offset", "schema": {"default": 0, "maximum": 2147483647, "title": "Offset", "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Posts on this workspace's boards, newest first unless you choose another\n`sort`. Filter by board, status, kind or free text. Each item has every\nfield of a post except `body_html` and `demand.trend`, which are left out to\nkeep long lists small. Fetch a single post to get those two as well.", "tags": ["posts"], "security": [{"KeyAuth": []}]}, "post": {"operationId": "apps_api_public_routers_create_post", "summary": "Create a post", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Payment Required", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "File a post, as the person the key belongs to.", "tags": ["posts"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/posts/{post_id}": {"get": {"operationId": "apps_api_public_routers_get_post", "summary": "Get a post", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostOut"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "One post in full, with its board, status, author, tags and demand.", "tags": ["posts"], "security": [{"KeyAuth": []}]}}, "/v1/posts/{post_id}/status": {"post": {"operationId": "apps_api_public_routers_set_post_status", "summary": "Move a post", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Give a post one of the workspace's statuses, by name. Only admins can do\nthis. A move to a new stage emails everyone who follows the post.", "tags": ["posts"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/StatusIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/posts/{post_id}/comments": {"get": {"operationId": "apps_api_public_routers_list_comments", "summary": "List comments", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}, {"in": "query", "name": "limit", "schema": {"default": 25, "title": "Limit", "type": "integer"}, "required": false}, {"in": "query", "name": "offset", "schema": {"default": 0, "maximum": 2147483647, "title": "Offset", "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommentList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Oldest first, in one flat list. A comment written while you page through\nis added at the end, so the pages you haven't read yet don't shift. On a\nreply, `parent_id` names the comment it answers.", "tags": ["comments"], "security": [{"KeyAuth": []}]}, "post": {"operationId": "apps_api_public_routers_add_comment", "summary": "Add a comment", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommentOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Reply on a post, as the person the key belongs to.", "tags": ["comments"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommentIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/posts/{post_id}/comments/{comment_id}/vote": {"post": {"operationId": "apps_api_public_routers_vote_comment", "summary": "Vote on a comment", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}, {"in": "path", "name": "comment_id", "schema": {"format": "uuid", "title": "Comment Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommentOut"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Add a vote to a comment, as the person the key belongs to. Voting twice\nstill counts as one vote.", "tags": ["comments"], "security": [{"KeyAuth": []}]}, "delete": {"operationId": "apps_api_public_routers_unvote_comment", "summary": "Remove a vote from a comment", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}, {"in": "path", "name": "comment_id", "schema": {"format": "uuid", "title": "Comment Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CommentOut"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Take a comment vote back. It's safe to repeat. Voting on a comment\ndoesn't follow anything, so there's nothing to unfollow.", "tags": ["comments"], "security": [{"KeyAuth": []}]}}, "/v1/statuses": {"get": {"operationId": "apps_api_public_routers_list_statuses", "summary": "List statuses", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StatusList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Every current status, and the stage each belongs to. Read this first, so\nyour client only sends `?status=` names that exist.", "tags": ["vocabulary"], "security": [{"KeyAuth": []}]}}, "/v1/tags": {"get": {"operationId": "apps_api_public_routers_list_tags", "summary": "List tags", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TagList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Every current tag in the workspace, in alphabetical order.", "tags": ["vocabulary"], "security": [{"KeyAuth": []}]}}, "/v1/posts/{post_id}/vote": {"post": {"operationId": "apps_api_public_routers_vote_post", "summary": "Vote on a post", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostOut"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Safe to repeat: voting twice still counts as one vote and sends one\nevent.", "tags": ["posts"], "security": [{"KeyAuth": []}]}, "delete": {"operationId": "apps_api_public_routers_unvote_post", "summary": "Remove a vote from a post", "parameters": [{"in": "path", "name": "post_id", "schema": {"format": "uuid", "title": "Post Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PostOut"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Take a vote back. It's safe to repeat. The person still follows the post,\nbecause following is separate, and they can stop following it on its own.", "tags": ["posts"], "security": [{"KeyAuth": []}]}}, "/v1/boards/{slug}": {"patch": {"operationId": "apps_api_public_routers_edit_board", "summary": "Edit a board", "parameters": [{"in": "path", "name": "slug", "schema": {"title": "Slug", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Payment Required", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Change a board's name, description, visibility and switches. Its address\nhas an endpoint of its own.", "tags": ["boards"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardPatch"}}}, "required": true}, "security": [{"KeyAuth": []}]}, "delete": {"operationId": "apps_api_public_routers_delete_board", "summary": "Delete a board", "parameters": [{"in": "path", "name": "slug", "schema": {"title": "Slug", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardOut"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Deleting a board hides it and its posts. Nothing is destroyed, and you\ncan bring it back from Settings, under Deleted.", "tags": ["boards"], "security": [{"KeyAuth": []}]}}, "/v1/boards/{slug}/address": {"put": {"operationId": "apps_api_public_routers_set_board_address", "summary": "Change a board address", "parameters": [{"in": "path", "name": "slug", "schema": {"title": "Slug", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Give a board a new address. Every address it has had keeps working, so a\nlink someone sent last year still opens the board.", "tags": ["boards"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/BoardAddressIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/members": {"get": {"operationId": "apps_api_public_routers_list_members", "summary": "List members", "parameters": [{"in": "query", "name": "role", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Role"}, "required": false}, {"in": "query", "name": "q", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Q"}, "required": false}, {"in": "query", "name": "limit", "schema": {"default": 25, "title": "Limit", "type": "integer"}, "required": false}, {"in": "query", "name": "offset", "schema": {"default": 0, "maximum": 2147483647, "title": "Offset", "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MemberList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Everyone in this workspace, newest first.", "tags": ["members"], "security": [{"KeyAuth": []}]}, "post": {"operationId": "apps_api_public_routers_invite_member", "summary": "Invite a member", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MemberOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Invite someone by email. The answer is the pending invitation, without\nits link, which goes only to their inbox.", "tags": ["members"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/MemberIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/members/{user_id}": {"patch": {"operationId": "apps_api_public_routers_set_member_role", "summary": "Promote or demote a member", "parameters": [{"in": "path", "name": "user_id", "schema": {"format": "uuid", "title": "User Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MemberOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Make someone an admin, or make an admin a member again. The last admin\ncan't step down, and gets a 409. Promote someone else first.", "tags": ["members"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/RoleIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}, "delete": {"operationId": "apps_api_public_routers_remove_member", "summary": "Remove a member", "parameters": [{"in": "path", "name": "user_id", "schema": {"format": "uuid", "title": "User Id", "type": "string"}, "required": true}], "responses": {"204": {"description": "No Content"}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "409": {"description": "Conflict", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "503": {"description": "Service Unavailable", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Take someone off this workspace. Their posts, votes and comments stay,\nbecause those belong to them, not to their place on the team.", "tags": ["members"], "security": [{"KeyAuth": []}]}}, "/v1/webhooks": {"get": {"operationId": "apps_api_public_routers_list_webhooks", "summary": "List webhooks", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Every endpoint this workspace sends events to, and how its recent\ndeliveries went.", "tags": ["webhooks"], "security": [{"KeyAuth": []}]}, "post": {"operationId": "apps_api_public_routers_add_webhook", "summary": "Add a webhook", "parameters": [], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSecret"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Payment Required", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Add an endpoint. The events you choose are sent to its URL, signed with a\nsecret. The secret is in this answer only, and no later request shows it\nagain.", "tags": ["webhooks"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}}, "/v1/webhooks/{endpoint_id}": {"put": {"operationId": "apps_api_public_routers_edit_webhook", "summary": "Edit a webhook", "parameters": [{"in": "path", "name": "endpoint_id", "schema": {"format": "uuid", "title": "Endpoint Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookOut"}}}}, "400": {"description": "Bad Request", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Change an endpoint's URL or the events it wants. Send the whole set each\ntime: a field you leave out is cleared, not kept.", "tags": ["webhooks"], "requestBody": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookIn"}}}, "required": true}, "security": [{"KeyAuth": []}]}, "delete": {"operationId": "apps_api_public_routers_remove_webhook", "summary": "Remove a webhook", "parameters": [{"in": "path", "name": "endpoint_id", "schema": {"format": "uuid", "title": "Endpoint Id", "type": "string"}, "required": true}], "responses": {"204": {"description": "No Content"}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Unlike everything else on this API, removing an endpoint is permanent. It\nholds a signing secret, and a removed secret shouldn't stay stored. Its\ndelivery log goes with it.", "tags": ["webhooks"], "security": [{"KeyAuth": []}]}}, "/v1/webhooks/{endpoint_id}/rotate": {"post": {"operationId": "apps_api_public_routers_rotate_webhook", "summary": "Rotate a webhook secret", "parameters": [{"in": "path", "name": "endpoint_id", "schema": {"format": "uuid", "title": "Endpoint Id", "type": "string"}, "required": true}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookSecret"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "404": {"description": "Not Found", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Get a new signing secret. It's shown in this answer only, and the old one\nstops working at once.", "tags": ["webhooks"], "security": [{"KeyAuth": []}]}}, "/v1/user-segments": {"get": {"operationId": "apps_api_public_routers_list_user_segments", "summary": "List user segments", "parameters": [{"in": "query", "name": "q", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Q"}, "required": false}, {"in": "query", "name": "label", "schema": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Label"}, "required": false}, {"in": "query", "name": "limit", "schema": {"default": 25, "title": "Limit", "type": "integer"}, "required": false}, {"in": "query", "name": "offset", "schema": {"default": 0, "maximum": 2147483647, "title": "Offset", "type": "integer"}, "required": false}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/UserSegmentList"}}}}, "401": {"description": "Unauthorized", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "402": {"description": "Payment Required", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "403": {"description": "Forbidden", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "422": {"description": "Unprocessable Content", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}, "429": {"description": "Too Many Requests", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}}}, "description": "Every user segment, largest first. **Team keys only.**", "tags": ["user-segments"], "security": [{"KeyAuth": []}]}}}, "components": {"schemas": {"BoardFieldOut": {"description": "One question a board asks on its submission form (0048).\n\nIts own copy rather than an import from `apps/api/schemas.py`, which is this\npackage's whole reason for existing: the v1 shapes are their own, so a field\nadded for the SPA cannot arrive on a published contract by accident.\n\n`key` is what `PostIn.field_values` is keyed by and what a `PostOut` answer\nnames, so an integrator reads this once per board and writes keys thereafter.\n`label` is presentation and may change under them, which is exactly why the\ntwo are separate.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "key": {"title": "Key", "type": "string"}, "label": {"title": "Label", "type": "string"}, "type": {"title": "Type", "type": "string"}, "required": {"default": false, "title": "Required", "type": "boolean"}, "help_text": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Help Text"}, "options": {"default": [], "items": {"type": "string"}, "title": "Options", "type": "array"}, "category_ids": {"default": [], "items": {"format": "uuid", "type": "string"}, "title": "Category Ids", "type": "array"}, "sort_order": {"title": "Sort Order", "type": "integer"}}, "required": ["id", "key", "label", "type", "sort_order"], "title": "BoardFieldOut", "type": "object"}, "BoardList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/BoardOut"}, "title": "Items", "type": "array"}}, "required": ["items"], "title": "BoardList", "type": "object"}, "BoardOut": {"properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "slug": {"title": "Slug", "type": "string"}, "name": {"title": "Name", "type": "string"}, "description": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Description"}, "visibility": {"title": "Visibility", "type": "string"}, "accepts_posts": {"default": true, "title": "Accepts Posts", "type": "boolean"}, "on_roadmap": {"default": true, "title": "On Roadmap", "type": "boolean"}, "closed_note": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Closed Note"}, "fields": {"default": [], "items": {"$ref": "#/components/schemas/BoardFieldOut"}, "title": "Fields", "type": "array"}, "attachment_prompt": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Attachment Prompt"}, "attachment_required": {"default": false, "title": "Attachment Required", "type": "boolean"}, "attachment_category_ids": {"default": [], "items": {"format": "uuid", "type": "string"}, "title": "Attachment Category Ids", "type": "array"}}, "required": ["id", "slug", "name", "visibility"], "title": "BoardOut", "type": "object"}, "Error": {"description": "Every refusal on this API. One shape, so a client branches on the status\nand reads `detail` for the sentence, which is `apps/api/schemas.Error`'s\narrangement and the same reason: a generated client should not have to know\na different error body per endpoint.", "properties": {"detail": {"title": "Detail", "type": "string"}}, "required": ["detail"], "title": "Error", "type": "object"}, "BoardIn": {"description": "A new board. Deliberately no switches (item 22).\n\nA board is born open and on the roadmap, which is what every board in this\nproduct was before 0036 and what the two columns default to. Creating one\nalready closed is creating one broken, and taking a brand-new board off the\nroadmap is one PATCH away.", "properties": {"slug": {"maxLength": 63, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "title": "Slug", "type": "string"}, "name": {"maxLength": 200, "minLength": 1, "title": "Name", "type": "string"}, "description": {"default": "", "maxLength": 5000, "title": "Description", "type": "string"}, "visibility": {"default": "public", "enum": ["public", "private"], "title": "Visibility", "type": "string"}}, "required": ["slug", "name"], "title": "BoardIn", "type": "object"}, "AuthorOut": {"description": "A byline. **`name` is nullable and that is the ordinary case**, not an\nexotic one: `app_user.name` is null until somebody sets it, and the two\ncommonest ways into this product cannot supply one at all -- a magic link\ncarries nothing but an address, and so does accepting an invitation. An SSO\nassertion may carry a `name` and it is taken on provisioning only (item 43),\nwhich narrows this case without closing it: a customer who sends no `name`,\nor an unusable one, still creates somebody null, and so does every person who\narrived before that existed.\n\nIt was `str` for a day. That is a 500 on the whole page rather than on one\nrow, because pydantic validates the response as a document, so a single\nnameless author would have taken `GET /v1/posts` down for a workspace. The\nSPA's `UserOut` has had `str | None` all along; this is that, one API over.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Name"}, "avatar_url": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Avatar Url"}}, "required": ["id"], "title": "AuthorOut", "type": "object"}, "DemandOut": {"description": "What a post's votes add up to once the voters have segments (item 56).\n\nIts own copy rather than an import from `apps/api/schemas.py`, which is this\npackage's whole reason for existing: the v1 shapes are their own, so a field\nadded for the SPA cannot arrive on a published contract by accident.\n\n**Facts as columns and never a score.** No field here blends votes and value\ninto a \"priority\", and none may be added: a generated client with a `score`\non it is this feature failing in the exact way the competitors' fail, and on\na surface where every integrator would then build against it.", "properties": {"user_segments": {"title": "User Segments", "type": "integer"}, "weight": {"title": "Weight", "type": "integer"}, "top_weight": {"title": "Top Weight", "type": "integer"}, "top_share": {"title": "Top Share", "type": "integer"}, "recent_user_segments": {"title": "Recent User Segments", "type": "integer"}}, "required": ["user_segments", "weight", "top_weight", "top_share", "recent_user_segments"], "title": "DemandOut", "type": "object"}, "FieldAnswerOut": {"description": "One answer, with the label it was given under.\n\nResolved rather than raw, which is `StatusOut`'s call: a client here would\notherwise hold `BoardOut.fields` and join per row, and that list carries live\ndefinitions only -- so an answer under a field the workspace has since\nstopped asking would arrive as a bare key with no label. A sync job mirroring\na board needs the label it was actually collected under.", "properties": {"key": {"title": "Key", "type": "string"}, "label": {"title": "Label", "type": "string"}, "type": {"title": "Type", "type": "string"}, "value": {"anyOf": [{"type": "string"}, {"type": "number"}, {"type": "boolean"}, {"items": {"type": "string"}, "type": "array"}], "title": "Value"}}, "required": ["key", "label", "type", "value"], "title": "FieldAnswerOut", "type": "object"}, "PageInfo": {"description": "One envelope for every list, so a client writes its paging once.\n\n`total` is the number of rows the filter matched and not the number in\n`items`, which is the rule the SPA's lists already follow and the one an\nintegrator needs to size a loop.", "properties": {"total": {"title": "Total", "type": "integer"}, "limit": {"title": "Limit", "type": "integer"}, "offset": {"title": "Offset", "type": "integer"}}, "required": ["total", "limit", "offset"], "title": "PageInfo", "type": "object"}, "PostList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/PostSummaryOut"}, "title": "Items", "type": "array"}, "page": {"$ref": "#/components/schemas/PageInfo"}}, "required": ["items", "page"], "title": "PostList", "type": "object"}, "PostSummaryOut": {"description": "A post as a **list** publishes it.\n\nEverything `PostOut` has except the two fields that only make sense one post\nat a time, and the split is 2026-09-18's. Both were measured on a real\nclient rather than argued:\n\n**`body_html` is not here.** It is `body` rendered, and `body` is on this\nshape -- so a list carried the same prose twice, in two formats, for every\nrow. `PostOut`'s own argument for keeping it is that an integrator should\nnot have to write a markdown renderer against our dialect and that\n`attachment:` references only resolve on our side. That argument is about\nreading *a* post and it is answered by the detail shape having it.\n\n**`demand.trend` is not here**, for the reason on `DemandDetailOut`.\n\n**What this cost before it existed**: a real agent calling `list_posts` with\n`limit=100` got a ~150,000 character result, which was over its client's\ntool-result cap -- so it never read the answer, it wrote it to a file and\nran `jq` over it. Four of its five pages went that way.\n\nNothing was moved behind a flag or a parameter, which was the other\ncandidate and is worse: a shape that changes with an argument cannot be\ndescribed by one `outputSchema`, and MCP requires a declared output schema\nto be conformed to.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "board_id": {"format": "uuid", "title": "Board Id", "type": "string"}, "board_slug": {"title": "Board Slug", "type": "string"}, "title": {"title": "Title", "type": "string"}, "body": {"title": "Body", "type": "string"}, "status": {"$ref": "#/components/schemas/StatusOut"}, "is_private": {"title": "Is Private", "type": "boolean"}, "vote_count": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Vote Count"}, "comment_count": {"title": "Comment Count", "type": "integer"}, "author": {"anyOf": [{"$ref": "#/components/schemas/AuthorOut"}, {"type": "null"}]}, "owner": {"anyOf": [{"$ref": "#/components/schemas/AuthorOut"}, {"type": "null"}]}, "tags": {"default": [], "items": {"$ref": "#/components/schemas/TagOut"}, "title": "Tags", "type": "array"}, "target_date": {"anyOf": [{"format": "date", "type": "string"}, {"type": "null"}], "title": "Target Date"}, "merged_into_id": {"anyOf": [{"format": "uuid", "type": "string"}, {"type": "null"}], "title": "Merged Into Id"}, "comments_locked": {"default": false, "title": "Comments Locked", "type": "boolean"}, "locked_note": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Locked Note"}, "created_at": {"format": "date-time", "title": "Created At", "type": "string"}, "updated_at": {"format": "date-time", "title": "Updated At", "type": "string"}, "status_changed_at": {"format": "date-time", "title": "Status Changed At", "type": "string"}, "demand": {"anyOf": [{"$ref": "#/components/schemas/DemandOut"}, {"type": "null"}]}, "field_answers": {"default": [], "items": {"$ref": "#/components/schemas/FieldAnswerOut"}, "title": "Field Answers", "type": "array"}}, "required": ["id", "board_id", "board_slug", "title", "body", "status", "is_private", "vote_count", "comment_count", "created_at", "updated_at", "status_changed_at"], "title": "PostSummaryOut", "type": "object"}, "StatusOut": {"description": "A workspace's own status, and the kind it belongs to (0015).\n\n**Both, and that is the one thing a client here must understand.** `name` is\nwhat the workspace calls it and changes when they rename it; `kind` is one of\nthe six values every consumer in this product actually branches on. A client\nfiltering on `name` breaks when an admin edits a settings page. The SPA's\n`?status=` versus `?kind=` pair is the same distinction and has already cost\nthis project a day.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "name": {"title": "Name", "type": "string"}, "kind": {"title": "Kind", "type": "string"}}, "required": ["id", "name", "kind"], "title": "StatusOut", "type": "object"}, "TagOut": {"description": "A tag has a name and a colour and **no slug**, unlike a board.\n\nWritten with one first, and the 500 that came back from a real workspace is\nthe reason this comment exists: every post in the test fixtures had no tags,\nso the field that does not exist was never serialised. A tag is the\nworkspace's own vocabulary and is identified by its name everywhere in this\nproduct, which is why `PostIn.tags` takes names.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "name": {"title": "Name", "type": "string"}, "color": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Color"}}, "required": ["id", "name"], "title": "TagOut", "type": "object"}, "DemandDetailOut": {"description": "The scalars above, plus the arrival series, for **one** post.\n\n**The series is on the detail shape and not on the list one** (2026-09-18),\nand the reason is a measurement rather than taste. `trend` is twelve weekly\nbuckets, and `rollup.py`'s `empty_trend` fills every week a post had no\nsegment arrive in with a zero -- so on a list of 25 posts it was **33% of\nthe whole response**, almost all of it zeros. A real agent asked to read a\npost's demand printed twelve rows of which eleven were `0`.\n\nIt is a chart series: one post, over time. On a list it is the same chart\nrepeated per row, which is a thing no reader wants and every reader pays\nfor. `GET /v1/posts/{id}` is where a caller asks about one post, so it is\nwhere the series belongs.", "properties": {"user_segments": {"title": "User Segments", "type": "integer"}, "weight": {"title": "Weight", "type": "integer"}, "top_weight": {"title": "Top Weight", "type": "integer"}, "top_share": {"title": "Top Share", "type": "integer"}, "recent_user_segments": {"title": "Recent User Segments", "type": "integer"}, "trend": {"default": [], "items": {"$ref": "#/components/schemas/DemandWeekOut"}, "title": "Trend", "type": "array"}}, "required": ["user_segments", "weight", "top_weight", "top_share", "recent_user_segments"], "title": "DemandDetailOut", "type": "object"}, "DemandWeekOut": {"description": "One bucket of the arrival series: a Monday and a count.", "properties": {"week": {"format": "date", "title": "Week", "type": "string"}, "user_segments": {"title": "User Segments", "type": "integer"}}, "required": ["week", "user_segments"], "title": "DemandWeekOut", "type": "object"}, "PostOut": {"description": "A post as a program sees it, in full.\n\nAgainst the SPA's `PostOut`, this drops `has_voted`, `is_following`,\n`pinned_comment`, `updated_by`, `excerpt` and `merged_into`. The first two\nare per viewer and meaningless for a shared key; the next two are drawing\nconcerns; `excerpt` is `body` truncated, which a caller can do and we should\nnot freeze the rule for; and `merged_into` is replaced by the plainer\n`merged_into_id`, because a nested post inside a post is a shape that\ninvites a client to walk it.\n\n**Against `PostSummaryOut` it adds the two fields that are worth their bytes\none post at a time and not a hundred**, which is 2026-09-18's split and is\nargued on that class. Every operation that answers with a *single* post uses\nthis shape -- `GET /v1/posts/{id}`, both votes, the status move, the edit,\nthe create -- so nothing an integrator could reach before has lost a field.\nOnly `GET /v1/posts` changed, and only by not repeating a rendering and a\nchart series on every row.\n\n`body_html` is the rendered markup `apps/content/render.py` produced,\nsanitised (D30). It is here because the alternative is every integrator\nwriting their own markdown renderer against our dialect, and `attachment:`\nreferences only resolve on our side.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "board_id": {"format": "uuid", "title": "Board Id", "type": "string"}, "board_slug": {"title": "Board Slug", "type": "string"}, "title": {"title": "Title", "type": "string"}, "body": {"title": "Body", "type": "string"}, "status": {"$ref": "#/components/schemas/StatusOut"}, "is_private": {"title": "Is Private", "type": "boolean"}, "vote_count": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Vote Count"}, "comment_count": {"title": "Comment Count", "type": "integer"}, "author": {"anyOf": [{"$ref": "#/components/schemas/AuthorOut"}, {"type": "null"}]}, "owner": {"anyOf": [{"$ref": "#/components/schemas/AuthorOut"}, {"type": "null"}]}, "tags": {"default": [], "items": {"$ref": "#/components/schemas/TagOut"}, "title": "Tags", "type": "array"}, "target_date": {"anyOf": [{"format": "date", "type": "string"}, {"type": "null"}], "title": "Target Date"}, "merged_into_id": {"anyOf": [{"format": "uuid", "type": "string"}, {"type": "null"}], "title": "Merged Into Id"}, "comments_locked": {"default": false, "title": "Comments Locked", "type": "boolean"}, "locked_note": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Locked Note"}, "created_at": {"format": "date-time", "title": "Created At", "type": "string"}, "updated_at": {"format": "date-time", "title": "Updated At", "type": "string"}, "status_changed_at": {"format": "date-time", "title": "Status Changed At", "type": "string"}, "demand": {"anyOf": [{"$ref": "#/components/schemas/DemandDetailOut"}, {"type": "null"}]}, "field_answers": {"default": [], "items": {"$ref": "#/components/schemas/FieldAnswerOut"}, "title": "Field Answers", "type": "array"}, "body_html": {"title": "Body Html", "type": "string"}}, "required": ["id", "board_id", "board_slug", "title", "body", "status", "is_private", "vote_count", "comment_count", "created_at", "updated_at", "status_changed_at", "body_html"], "title": "PostOut", "type": "object"}, "PostIn": {"description": "Creating one. `board` is a slug rather than an id on purpose.\n\nAn integrator writing a script knows the board is called `feedback`; making\nthem look up a uuid first is a round trip that exists only because our\nprimary key does. Ids are accepted everywhere they identify an existing\nthing, and this is the one place a human-chosen name is the better handle.", "properties": {"board": {"title": "Board", "type": "string"}, "title": {"maxLength": 300, "minLength": 1, "title": "Title", "type": "string"}, "body": {"default": "", "maxLength": 50000, "title": "Body", "type": "string"}, "is_private": {"default": false, "title": "Is Private", "type": "boolean"}, "tags": {"default": [], "items": {"type": "string"}, "title": "Tags", "type": "array"}, "field_values": {"additionalProperties": true, "default": {}, "title": "Field Values", "type": "object"}}, "required": ["board", "title"], "title": "PostIn", "type": "object"}, "StatusIn": {"description": "Moving a post. The status is named, for `PostIn.board`'s reason, and by\nthe workspace's own word rather than by kind: two statuses can share a kind\nand only one of them is the one the admin meant.", "properties": {"status": {"title": "Status", "type": "string"}, "reason": {"default": "", "maxLength": 20000, "title": "Reason", "type": "string"}}, "required": ["status"], "title": "StatusIn", "type": "object"}, "CommentList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/CommentOut"}, "title": "Items", "type": "array"}, "page": {"$ref": "#/components/schemas/PageInfo"}}, "required": ["items", "page"], "title": "CommentList", "type": "object"}, "CommentOut": {"description": "A comment. `is_internal` is the team-only flag and is published because a\nkey is an admin's: what it must never do is reach a caller who is not on the\nteam, and on this host there is no such caller.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "post_id": {"format": "uuid", "title": "Post Id", "type": "string"}, "body": {"title": "Body", "type": "string"}, "body_html": {"title": "Body Html", "type": "string"}, "author": {"anyOf": [{"$ref": "#/components/schemas/AuthorOut"}, {"type": "null"}]}, "is_internal": {"title": "Is Internal", "type": "boolean"}, "vote_count": {"default": 0, "title": "Vote Count", "type": "integer"}, "created_at": {"format": "date-time", "title": "Created At", "type": "string"}}, "required": ["id", "post_id", "body", "body_html", "is_internal", "created_at"], "title": "CommentOut", "type": "object"}, "CommentIn": {"properties": {"body": {"maxLength": 20000, "minLength": 1, "title": "Body", "type": "string"}, "is_internal": {"default": false, "title": "Is Internal", "type": "boolean"}}, "required": ["body"], "title": "CommentIn", "type": "object"}, "StatusList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/StatusOut"}, "title": "Items", "type": "array"}}, "required": ["items"], "title": "StatusList", "type": "object"}, "TagList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/TagOut"}, "title": "Items", "type": "array"}}, "required": ["items"], "title": "TagList", "type": "object"}, "BoardPatch": {"description": "The whole set every time, and the two switches default to what a board\nhas always done: a script written before 0036 that renames a board leaves it\nopen and on the roadmap, where it already was.", "properties": {"name": {"maxLength": 200, "minLength": 1, "title": "Name", "type": "string"}, "description": {"default": "", "maxLength": 5000, "title": "Description", "type": "string"}, "visibility": {"default": "public", "enum": ["public", "private"], "title": "Visibility", "type": "string"}, "accepts_posts": {"default": true, "title": "Accepts Posts", "type": "boolean"}, "on_roadmap": {"default": true, "title": "On Roadmap", "type": "boolean"}, "closed_note": {"default": "", "maxLength": 120, "title": "Closed Note", "type": "string"}}, "required": ["name"], "title": "BoardPatch", "type": "object"}, "BoardAddressIn": {"description": "A board's new address (0070). Its own body, one field.\n\nThe SPA's own `BoardAddressIn` and the same argument: it is not on\n`BoardPatch` because that is a whole-set body, and 0053's defect is that a\nfield added to one of those makes an omission and a clear the same JSON.\n\nThe pattern is `board.slug`'s CHECK, repeated for the reason every bound in\nthis file is: a 422 that names the field beats an IntegrityError.\n\n**`address` where the SPA's twin says `slug`** (item 58), and the divergence\nis this file's own rule rather than drift: the v1 shapes are their own, which\nis why `PostIn` here takes a board's address where the SPA's takes a\n`board_id`. Two things decided it. The endpoint is `set_board_address`, the\npath ends `/address` and the table is `board_address`, so `slug` was the one\nword in that sentence not saying what the others say. And the path parameter\nis *also* called `slug` and means the opposite end of the same act -- which\nboard, rather than what to call it -- which is survivable in REST, where a\npath and a body are different namespaces, and is not survivable in a tool\ncall, where they are one flat object. `apps/api/public/mcp.py` refuses to\nbuild a catalogue with a collision in it rather than silently losing one of\nthe two, and this is the collision it found.\n\nFree because it was asked rather than assumed: production held **0 API\nkeys** on 2026-09-18, so nothing has ever been built against this contract.\nAfter the first key is issued this is a breaking change with no deprecation\nwindow, like every other name on the wire.", "properties": {"address": {"maxLength": 63, "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$", "title": "Address", "type": "string"}}, "required": ["address"], "title": "BoardAddressIn", "type": "object"}, "MemberList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/MemberOut"}, "title": "Items", "type": "array"}, "page": {"$ref": "#/components/schemas/PageInfo"}}, "required": ["items", "page"], "title": "MemberList", "type": "object"}, "MemberOut": {"description": "Somebody in this workspace, with their address. See the module head.\n\n`role` is `admin`, `member` or `end_user`, and the third is the majority:\n`membership` is written on first interaction, so this list is everybody who\nhas ever voted, not just the team. An integrator syncing a team wants\n`?role=admin,member` and should say so rather than paging five thousand\ncustomers.", "properties": {"user_id": {"format": "uuid", "title": "User Id", "type": "string"}, "email": {"title": "Email", "type": "string"}, "name": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Name"}, "role": {"title": "Role", "type": "string"}, "created_at": {"format": "date-time", "title": "Created At", "type": "string"}}, "required": ["user_id", "email", "role", "created_at"], "title": "MemberOut", "type": "object"}, "MemberIn": {"description": "An invitation. Answers with the row and never with the link.\n\nThe secret in an invitation is emailed and is not returned here, unlike an\nAPI key's, and the difference is who it is for: a key's secret is handed to\nthe person who asked for it, and an invitation's is a credential for\nsomebody else. Returning it would make this endpoint a way to mint a\nsign-in for any address, which is what `POST /changelog/subscribe` is gated\nfor one door over.", "properties": {"email": {"format": "email", "maxLength": 254, "pattern": "^[A-Za-z0-9!#$%&'*+\\/=?^_`\\{\\|\\}~.\\-]+@([A-Za-z0-9]([A-Za-z0-9\\-]*[A-Za-z0-9])?\\.)+[A-Za-z0-9]([A-Za-z0-9\\-]*[A-Za-z0-9])?$", "title": "Email", "type": "string"}, "role": {"default": "member", "enum": ["admin", "member"], "title": "Role", "type": "string"}}, "required": ["email"], "title": "MemberIn", "type": "object"}, "RoleIn": {"properties": {"role": {"enum": ["admin", "member"], "title": "Role", "type": "string"}}, "required": ["role"], "title": "RoleIn", "type": "object"}, "WebhookList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/WebhookOut"}, "title": "Items", "type": "array"}, "deliverable": {"items": {"type": "string"}, "title": "Deliverable", "type": "array"}, "opt_in": {"items": {"type": "string"}, "title": "Opt In", "type": "array"}}, "required": ["items", "deliverable", "opt_in"], "title": "WebhookList", "type": "object"}, "WebhookOut": {"description": "An endpoint. **Never the signing secret**, since 2026-09-18.\n\nIt carried one until then, on the argument that \"the workspace needs it and\nthis is the workspace asking\". That was true and it was not the whole\nquestion: the secret was on *every read*, so every caller entitled to list\nendpoints was handed the HMAC key every receiver verifies with, on every\nrequest, for ever.\n\n**The rule is keyed on the field and not on the kind of key**, which is the\nthird answer to that and the only one that holds. Keying it on the kind was\ntried first and is written up in `CLAUDE.md`: a `read_only` key was refused\nthis operation while a `read_write` and an `mcp` key were not, and the hole\nthat leaves is `edit_webhook` -- a PUT that changes nothing came back with\nthe same secret, measured. So an exception list would have had to name four\noperations and one shared serialiser, and the next one added would inherit\nthe default rather than the exception.\n\nSo the secret exists in **exactly two responses** in this API, both of them\nthe moment it is minted: `POST /v1/webhooks` and `POST /v1/webhooks/{id}/\nrotate`, both answering `WebhookSecret`. That is `ApiKeyCreated`'s\narrangement one table over, and its argument applies unchanged -- an\noptional `secret` here would be a shape whose sensitive half is invisible in\nthe type, and every client reading the list would be reading a schema that\nclaims a credential might be in it.\n\n**The cost is stated rather than discovered**: an integrator who loses the\nsecret cannot read it back and has to rotate, which breaks their receiver's\nverification until the new one is in its configuration. That is the same\ntrade this product already makes for API keys, and it is the reason\n`rotate_webhook` answers with the secret rather than with a bare 204.\n\n`health` is `healthy`, `failing` or `unknown`, read from the most recent\nattempt, which is the one field a monitoring script actually wants. The\ndelivery log itself is not here: it is up to ten bodies per endpoint and is\na page's concern, and an endpoint that wants its own history has it.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "url": {"title": "Url", "type": "string"}, "event_types": {"items": {"type": "string"}, "title": "Event Types", "type": "array"}, "is_active": {"title": "Is Active", "type": "boolean"}, "health": {"title": "Health", "type": "string"}, "created_at": {"format": "date-time", "title": "Created At", "type": "string"}}, "required": ["id", "url", "event_types", "is_active", "health", "created_at"], "title": "WebhookOut", "type": "object"}, "WebhookSecret": {"description": "An endpoint plus the signing secret, which is answered twice and never\nagain: when it is created and when it is rotated.\n\nIts own schema rather than `WebhookOut` with an optional field, for\n`ApiKeyCreated`'s reason: a shape that *might* carry a credential is one\nevery reader has to check, and a type that says so at the two call sites\nthat really do is one nobody has to.\n\n`endpoint` and not the fields inline, so the thing a caller stores and the\nthing a caller reads are the same shape with the same names -- a flattened\nvariant here would be a second definition of an endpoint that drifts the day\na field is added to one of them.", "properties": {"endpoint": {"$ref": "#/components/schemas/WebhookOut"}, "secret": {"title": "Secret", "type": "string"}}, "required": ["endpoint", "secret"], "title": "WebhookSecret", "type": "object"}, "WebhookIn": {"properties": {"url": {"maxLength": 2048, "minLength": 8, "title": "Url", "type": "string"}, "event_types": {"default": [], "items": {"type": "string"}, "title": "Event Types", "type": "array"}, "is_active": {"default": true, "title": "Is Active", "type": "boolean"}}, "required": ["url"], "title": "WebhookIn", "type": "object"}, "UserSegmentList": {"properties": {"items": {"items": {"$ref": "#/components/schemas/UserSegmentOut"}, "title": "Items", "type": "array"}, "page": {"$ref": "#/components/schemas/PageInfo"}}, "required": ["items", "page"], "title": "UserSegmentList", "type": "object"}, "UserSegmentOut": {"description": "One user segment, as an integrator sees it (item 56).\n\n**`external_id` is the field this shape exists for.** It is the key the\nsegment arrived under -- a Stripe customer id, a Donorbox donor id, whatever\nan SSO token sent -- so an integrator joins this list against their own\nsystem on a value they already hold, rather than on a name somebody may\nrename. Null only for a segment somebody typed by hand.\n\n`source` rides along because \"why does this say $2,000\" is answerable with\n\"Stripe said so, at this time\" and is otherwise not answerable at all.\n\nNo `emails` and no member list, deliberately. Who is in a segment is\n`GET /v1/members` joined on the workspace, and publishing a customer's\naddresses grouped by how much they pay is a shape this API declines to\nhand out in one response.", "properties": {"id": {"format": "uuid", "title": "Id", "type": "string"}, "external_id": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "External Id"}, "name": {"title": "Name", "type": "string"}, "label": {"anyOf": [{"type": "string"}, {"type": "null"}], "title": "Label"}, "value_cents": {"anyOf": [{"type": "integer"}, {"type": "null"}], "title": "Value Cents"}, "source": {"title": "Source", "type": "string"}, "member_count": {"default": 0, "title": "Member Count", "type": "integer"}, "pending_count": {"default": 0, "title": "Pending Count", "type": "integer"}, "created_at": {"format": "date-time", "title": "Created At", "type": "string"}, "updated_at": {"format": "date-time", "title": "Updated At", "type": "string"}}, "required": ["id", "name", "source", "created_at", "updated_at"], "title": "UserSegmentOut", "type": "object"}}, "securitySchemes": {"KeyAuth": {"type": "http", "scheme": "bearer"}}}, "servers": [], "tags": [{"name": "posts", "description": "Posts are the requests people file on your boards. Comments, votes and statuses all belong to a post."}, {"name": "comments", "description": "The conversation under a post. When an admin moves a post and gives a reason, the reason appears here as a comment."}, {"name": "boards", "description": "Boards hold posts. Most workspaces have two or three, and each one is addressed by its slug."}, {"name": "vocabulary", "description": "Statuses and tags, in your workspace's own words. Each status has a name you chose and a stage we define, called its kind. Filter with `?status=` for a name or `?kind=` for a stage, and a wrong value in either returns an error, not an empty list. Tags are matched by name, and a tag that doesn't exist isn't created for you."}, {"name": "members", "description": "Everyone who has ever taken part in the workspace, which is mostly customers, not your team. Ask for `?role=admin,member` to get just the team."}, {"name": "user-segments", "description": "Who your customers are, and what each is worth to you. A segment is whatever unit you're paid by: a company with twelve people in it, or one subscriber or donor. Voters belong to segments, so a post shows how many separate segments asked for it and the weight behind them, not only a vote count. Every value is in minor units, like cents. **These need a key that belongs to someone on your team.** For any other key, `demand` on a post is null. You told us this about your customers, and it's never shown to anyone else."}, {"name": "webhooks", "description": "The addresses we send events to. You see an endpoint's signing secret once, when you add it or rotate it, so keep it somewhere safe. An empty event list means every type except the high-volume ones, which you have to name. Nothing about a user segment is ever sent here."}]}