{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Finery API", "version": "0.1.0", "summary": "Forge a business idea into a tested offer.", "description": "Finery forges a business idea into a tested offer. Describe the idea in your own words; Finery interviews you, asking only for what it could not work out, then writes the Results: names, positioning, a pitch, CEO, CFO and tech question packs, and launch Checks.\n\nFlow: `POST /api/sessions` creates an Idea. `POST /api/sessions/{id}/interview` sends the description, then each answer (or `assume_rest: true`) until `ready` is true. Forging is two calls: `POST /api/sessions/{id}/confirm`, then `POST /api/sessions/{id}/bundle`. `GET /api/sessions/{id}/bundle` reads the Results and `GET /api/sessions/{id}/export.md` the brief.\n\nAuth depends on the deployment. Open mode (production today): send `X-Finery-Owner` with an id you choose; it scopes your Ideas and is not authentication. Clerk mode (previews): send `Authorization: Bearer` with a Clerk session token whose user has an active Organisation, or an Organisation API key. The owner header is ignored in clerk mode.\n\nAgents can also use the MCP server at https://finery.dev/mcp (Streamable HTTP, no sign-in). See https://finery.dev/llms.txt.\n\nPrice: EUR 9 per Forged Idea. Payment is not live yet: there is no checkout, and nothing is charged during the early preview." }, "externalDocs": { "description": "llms.txt", "url": "https://finery.dev/llms.txt" }, "servers": [ { "url": "https://finery.dev" } ], "tags": [ { "name": "Ideas", "description": "An Idea and its canvas." }, { "name": "Interview", "description": "The conversation that fills the canvas." }, { "name": "Results", "description": "Forging, and the Results of a Forged Idea." }, { "name": "Export", "description": "The brief." }, { "name": "Comments", "description": "Plain-text comments on the sections of the Results." }, { "name": "Side opportunities", "description": "Optional side opportunities. Off by default." }, { "name": "Sample", "description": "The labelled fictional sample Idea." }, { "name": "Service", "description": "Operations." } ], "security": [ { "ownerHeader": [] }, { "clerkBearer": [] } ], "paths": { "/health": { "get": { "operationId": "getHealth", "summary": "Liveness check", "tags": [ "Service" ], "security": [], "responses": { "200": { "description": "The worker is up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } } } }, "/api/ideas": { "get": { "operationId": "listIdeas", "summary": "List your Ideas", "description": "The caller's Ideas, most recently changed first (at most 200). Needs a real identity: in clerk mode the signed-in Organisation; without sign-in it answers only on a local host, because the owner header is shared by every visitor.", "tags": [ "Ideas" ], "responses": { "200": { "description": "The Ideas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdeaList" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions": { "post": { "operationId": "createIdea", "summary": "Start an Idea", "description": "Creates an empty Idea owned by the caller. Then send the description with `POST /api/sessions/{id}/interview`.", "tags": [ "Ideas" ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "The new Idea.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}": { "get": { "operationId": "getIdea", "summary": "Read an Idea", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Idea.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteIdea", "summary": "Delete an Idea", "description": "Deletes the Idea and everything stored with it (canvas, Results, versions, Checks). Cannot be undone. Same identity rule as listing.", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/interview": { "get": { "operationId": "getInterview", "summary": "Where the interview stands", "description": "What is missing, the open questions, whether the Idea is ready to forge, and the canvas. Runs no turn.", "tags": [ "Interview" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The interview state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "sendInterviewTurn", "summary": "Answer, describe, or assume the rest", "description": "One interview turn. `message` is free text: the first description of the Idea, answers to the open questions, or any further detail. `assume_rest: true` asks Finery to fill every required answer still missing with a labelled assumption (it needs the model; without it nothing is assumed). Only pass on what the person said.", "tags": [ "Interview" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InterviewTurnRequest" } } } }, "responses": { "200": { "description": "The turn's result and the canvas after it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Interview" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The canvas changed during this turn; nothing was saved (`conflict`). Send it again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/canvas": { "get": { "operationId": "getCanvas", "summary": "Read the canvas", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The canvas.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Canvas" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "operationId": "saveCanvas", "summary": "Autosave the canvas", "description": "Merges `document` into the stored canvas. `version` is the canvas version the edit was based on; a stale base that would overwrite other fields is refused with 409.", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanvasAutosave" } } } }, "responses": { "200": { "description": "The canvas after the merge.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Canvas" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another write won the race (`conflict`). Re-read and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/ready": { "get": { "operationId": "getReady", "summary": "Is the canvas ready to forge", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Ready, and what is missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ready" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/confirm": { "get": { "operationId": "getConfirmation", "summary": "Read the confirmation", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whether the current canvas is confirmed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Confirmation" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "confirmCanvas", "summary": "Confirm the canvas (step 1 of forging)", "description": "Freezes the current canvas as a forge version. Refused until the ready check passes.", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The confirmation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Confirmation" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not ready (`canvas_not_ready`, with `missing`) or a version collision (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/versions": { "post": { "operationId": "createSnapshot", "summary": "Store a canvas snapshot", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "The snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another write won the race (`conflict`). Re-read and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/versions/{n}": { "get": { "operationId": "getSnapshot", "summary": "Read a canvas snapshot", "tags": [ "Ideas" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "n", "in": "path", "required": true, "description": "A forge version: a positive integer.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The snapshot.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/bundle": { "get": { "operationId": "getResults", "summary": "Read the Results", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Results: names, positioning, pitch, question packs and Checks.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bundle" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such Idea (`not_found`), or nothing forged yet (`bundle_not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "forgeResults", "summary": "Forge the Results (step 2 of forging)", "description": "Writes every block of the Results and runs the launch Checks, from the confirmed canvas. Confirm first. Can take a minute. Price: EUR 9 per Forged Idea. Payment is not live yet: there is no checkout, and nothing is charged during the early preview.", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "The Forged Idea's Results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bundle" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not confirmed or stale (`canvas_not_confirmed`), or a version collision (`conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The model's answer failed validation (`bundle_validation`). Nothing was stored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/bundle/blocks/{block}": { "post": { "operationId": "regenerateBlock", "summary": "Write one block of the Results again", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "block", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack" ] } } ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The Results with the new block.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bundle" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`canvas_not_confirmed`, `bundle_not_generated`, `bundle_stale`, or `conflict`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The model's answer failed validation (`bundle_validation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/bundle/diff": { "get": { "operationId": "diffResults", "summary": "Compare two versions of the Results", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleDiff" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/bundle/restore": { "post": { "operationId": "restoreResults", "summary": "Restore an earlier version of the Results", "description": "Appends a new version copied from `forge_version`. Earlier versions are never edited.", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreRequest" } } } }, "responses": { "201": { "description": "The Results after the restore.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Bundle" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Another write won the race (`conflict`). Re-read and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/bundle/versions": { "get": { "operationId": "listResultVersions", "summary": "List the versions of the Results", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every stored version, oldest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleVersionList" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/bundle/versions/{n}": { "get": { "operationId": "getResultVersion", "summary": "Read one version of the Results", "tags": [ "Results" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "n", "in": "path", "required": true, "description": "A forge version: a positive integer.", "schema": { "type": "integer", "minimum": 1 } } ], "responses": { "200": { "description": "The stored version.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BundleVersion" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/selections": { "get": { "operationId": "getSelections", "summary": "Read what was accepted from the Results", "tags": [ "Export" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The stored selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionView" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "saveSelections", "summary": "Choose what goes into the brief", "tags": [ "Export" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionRequest" } } } }, "responses": { "200": { "description": "The stored selection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SelectionView" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not ready for this yet: `canvas_not_ready`, `canvas_not_confirmed`, `bundle_not_generated` or `bundle_stale`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/comments": { "get": { "operationId": "listComments", "summary": "Read the comments on the Results", "description": "Every comment on this Idea, oldest first. Each is plain text on one section of the Results.", "tags": [ "Comments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Idea's comments.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentList" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createComment", "summary": "Comment on a section of the Results", "tags": [ "Comments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentCreateRequest" } } } }, "responses": { "201": { "description": "The stored comment.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The Idea already holds the most comments it keeps (`comment_limit`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/comments/{commentId}": { "patch": { "operationId": "updateComment", "summary": "Edit a comment", "tags": [ "Comments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "description": "The comment id (the `id` returned when it was created).", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommentUpdateRequest" } } } }, "responses": { "200": { "description": "The comment with its new text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Comment" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such Idea, or no such comment on it, for the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "operationId": "deleteComment", "summary": "Delete a comment", "tags": [ "Comments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "commentId", "in": "path", "required": true, "description": "The comment id (the `id` returned when it was created).", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Deleted." }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No such Idea, or no such comment on it, for the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/export": { "get": { "operationId": "exportBrief", "summary": "Export the brief as JSON", "tags": [ "Export" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "debug", "in": "query", "required": false, "description": "`1` cites raw canvas field paths.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "The brief, as Markdown and as a Linear issue.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not ready for this yet: `canvas_not_ready`, `canvas_not_confirmed`, `bundle_not_generated` or `bundle_stale`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/export.md": { "get": { "operationId": "exportBriefMarkdown", "summary": "Export the brief as Markdown", "tags": [ "Export" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "brief", "linear" ], "default": "brief" } }, { "name": "debug", "in": "query", "required": false, "description": "`1` cites raw canvas field paths.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "The brief.", "content": { "text/markdown": { "schema": { "type": "string" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Not ready for this yet: `canvas_not_ready`, `canvas_not_confirmed`, `bundle_not_generated` or `bundle_stale`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/opportunities": { "get": { "operationId": "listOpportunities", "summary": "Read the side opportunities", "tags": [ "Side opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The scan setting and stored opportunities.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityList" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "put": { "operationId": "setOpportunityScan", "summary": "Turn the side-opportunity scan on or off", "tags": [ "Side opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunitySettings" } } } }, "responses": { "200": { "description": "The list after the change.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityList" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/opportunities/scan": { "post": { "operationId": "scanOpportunities", "summary": "Scan for side opportunities", "description": "Sample text only for now. The scan must be on, and the canvas confirmed.", "tags": [ "Side opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "The list with the new scan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityList" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The scan is off (`opportunity_scan_disabled`) or the canvas is not confirmed (`canvas_not_confirmed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The scan's answer failed validation (`opportunity_validation`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/sessions/{id}/opportunities/{opportunityId}": { "post": { "operationId": "decideOpportunity", "summary": "Accept or reject a side opportunity", "tags": [ "Side opportunities" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The Idea id (the `id` returned by `POST /api/sessions`).", "schema": { "type": "string" } }, { "name": "opportunityId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityDecision" } } } }, "responses": { "200": { "description": "The list after the decision.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityList" } } } }, "400": { "description": "The request failed validation (`validation`). `fields` lists each path and rule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`scan_disabled`, `opportunity_stale`, `opportunity_already_decided` or `opportunity_cap`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/demo/sample": { "get": { "operationId": "getSampleIdea", "summary": "Read the labelled sample Idea", "tags": [ "Sample" ], "responses": { "200": { "description": "The caller's sample Idea.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleSession" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/demo/seed": { "post": { "operationId": "seedSampleIdea", "summary": "Write the fictional sample Idea (local and preview only)", "description": "Refused with 404 on production, and unless the `x-finery-sample-seed` opt-in header is sent from localhost or an allowed preview host.", "tags": [ "Sample" ], "parameters": [ { "name": "x-finery-sample-seed", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "description": "No body is needed. A body, when sent, must be JSON; it is ignored.", "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "The sample Idea already existed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleSeed" } } } }, "201": { "description": "The sample Idea was written.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SampleSeed" } } } }, "401": { "description": "Open mode: the `X-Finery-Owner` header is missing or malformed (`owner_required`). Clerk mode: no valid Clerk session token or Organisation API key (`sign_in_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Clerk mode: signed in, but with no active Organisation (`organisation_required`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No Idea with this id belongs to the caller (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "`sample_seed_failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The request body is over 256 KB (`payload_too_large`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "A body was sent without `Content-Type: application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "`sample_seed_failed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Sign-in is on but the worker's configuration is incomplete (`auth_not_configured`), or the database schema is not migrated (`schema_not_migrated`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "ownerHeader": { "type": "apiKey", "in": "header", "name": "X-Finery-Owner", "description": "Open mode only. A placeholder owner id you choose (1–128 of A–Z a–z 0–9 . _ : @ -, starting with a letter or digit). Every Idea is scoped to it. It is not authentication: keep it unguessable." }, "clerkBearer": { "type": "http", "scheme": "bearer", "description": "Clerk mode only. A Clerk session token (the browser's `getToken()`) for a user with an active Organisation, or a Clerk API key issued to an Organisation. The Organisation owns the Ideas." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Short human title." }, "code": { "type": "string", "description": "Stable machine code, e.g. validation, not_found, conflict, owner_required, sign_in_required, organisation_required, auth_not_configured, schema_not_migrated, payload_too_large, unsupported_media_type, canvas_not_ready, canvas_not_confirmed, bundle_not_generated, bundle_stale, bundle_not_found, bundle_validation." }, "message": { "type": "string" }, "fields": { "description": "Validation: each failing path and rule. Conflict: the conflicting field paths.", "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } }, { "type": "array", "items": { "type": "string" } } ] }, "version": { "type": "integer", "description": "Conflict only: the current version." }, "updated_at": { "type": "string", "description": "Conflict only: when the current version was written." }, "missing": { "type": "array", "items": { "type": "string" }, "description": "canvas_not_ready only: the canvas fields still missing." }, "stale": { "type": "boolean", "description": "canvas_not_confirmed only: true when the canvas changed after confirm." }, "failures": { "type": "array", "description": "bundle_validation and opportunity_validation only.", "items": { "type": "object", "properties": { "block": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "error", "code" ] }, "Session": { "type": "object", "properties": { "id": { "type": "string" }, "owner_id": { "type": "string" }, "tenant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sample": { "type": "boolean", "description": "True for the labelled fictional sample Idea." }, "sample_marker": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "canvas_updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "owner_id", "tenant_id", "sample", "sample_marker", "created_at", "updated_at", "canvas_version", "canvas_updated_at" ] }, "IdeaList": { "type": "object", "properties": { "ideas": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "The first offer line, with the customer segment when the offer is short." }, "state": { "type": "string", "enum": [ "workshop", "ready", "forging", "forged" ] }, "blocks": { "type": "integer", "description": "Results blocks written so far; 6 once forged." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "state", "blocks", "created_at", "updated_at" ] } } }, "required": [ "ideas" ] }, "SampleSession": { "allOf": [ { "$ref": "#/components/schemas/Session" }, { "type": "object", "properties": { "sample_count": { "type": "integer" } }, "required": [ "sample_count" ] } ] }, "SampleSeed": { "type": "object", "properties": { "id": { "type": "string" }, "owner_id": { "type": "string" }, "tenant_id": { "type": "null" }, "sample": { "const": true }, "sample_marker": { "type": "string" }, "created": { "type": "boolean" }, "sample_count": { "type": "integer" }, "names_version": { "type": "integer" }, "block_versions": { "type": "object", "properties": { "names": { "type": "integer" }, "positioning": { "type": "integer" }, "pitch": { "type": "integer" }, "ceo_pack": { "type": "integer" } }, "required": [ "names", "positioning", "pitch", "ceo_pack" ] }, "bundle_versions": { "type": "array", "items": { "type": "integer" } } }, "required": [ "id", "owner_id", "tenant_id", "sample", "sample_marker", "created", "sample_count", "names_version", "block_versions", "bundle_versions" ] }, "CanvasDraft": { "type": "object", "properties": { "value_map": { "type": "object", "properties": { "products_services": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 } }, "required": [ "id", "text" ], "additionalProperties": false } }, "pain_relievers": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 }, "pain_id": { "type": "string", "maxLength": 80 } }, "required": [ "id", "text", "pain_id" ], "additionalProperties": false } }, "gain_creators": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 }, "gain_id": { "type": "string", "maxLength": 80 } }, "required": [ "id", "text", "gain_id" ], "additionalProperties": false } } }, "additionalProperties": false }, "customer_profile": { "type": "object", "properties": { "segment_name": { "type": "string", "maxLength": 200 }, "segment_description": { "type": "string", "maxLength": 4000 }, "jobs": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 }, "tag": { "type": "string", "enum": [ "functional", "social", "emotional" ] } }, "required": [ "id", "text", "tag" ], "additionalProperties": false } }, "pains": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 } }, "required": [ "id", "text" ], "additionalProperties": false } }, "gains": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 } }, "required": [ "id", "text" ], "additionalProperties": false } }, "competitors": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "additionalProperties": false }, "gtm": { "type": "object", "properties": { "value_prop_one_liner": { "type": "string", "maxLength": 500 }, "differentiation_claim": { "type": "string", "maxLength": 2000 }, "primary_channel": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "direct", "partner", "content", "outbound", "community", "product_led", "marketplace", "other" ] }, "detail": { "type": "string", "maxLength": 500 } }, "required": [ "kind", "detail" ], "additionalProperties": false }, "proof_needed": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "pricing": { "type": "object", "properties": { "pricing_motion": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "subscription", "usage", "project", "marketplace", "other" ] }, "detail": { "type": "string", "maxLength": 500 } }, "required": [ "kind", "detail" ], "additionalProperties": false }, "comps": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "maxLength": 200 }, "model": { "type": "string", "maxLength": 200 }, "published_price_band": { "type": "string", "maxLength": 200 }, "source_url": { "type": "string", "maxLength": 2000 }, "checked_date": { "type": "string" } }, "required": [ "id", "name", "model", "published_price_band", "source_url", "checked_date" ], "additionalProperties": false } }, "tiers": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "maxLength": 200 }, "who": { "type": "string", "maxLength": 500 }, "price": { "type": "string", "maxLength": 200 }, "included": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "name", "who", "price", "included" ], "additionalProperties": false } }, "recommended_band": { "type": "object", "properties": { "low": { "type": "number", "minimum": 0 }, "high": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 1, "maxLength": 8 }, "unit": { "type": "string", "enum": [ "seat", "workspace", "session", "usage" ] } }, "required": [ "low", "high", "currency", "unit" ], "additionalProperties": false }, "rationale": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "field_id": { "type": "string", "maxLength": 200 } }, "required": [ "text", "field_id" ], "additionalProperties": false } }, "additionalProperties": false }, "outputs": { "type": "object", "properties": { "names": { "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "positioning": { "type": "object", "properties": { "primary": { "type": "string", "maxLength": 500 }, "alternate": { "type": "string", "maxLength": 500 } }, "required": [ "primary", "alternate" ], "additionalProperties": false }, "pitches": { "type": "object", "properties": { "tagline_5s": { "type": "string", "maxLength": 280 }, "pitch_30s": { "type": "string", "maxLength": 2000 } }, "required": [ "tagline_5s", "pitch_30s" ], "additionalProperties": false }, "buyer_packs": { "type": "object", "properties": { "ceo": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "id", "question" ], "additionalProperties": false } } }, "required": [ "ceo" ], "additionalProperties": false }, "implied_capabilities": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 300 }, "source_field_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "text", "source_field_id" ], "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false, "description": "The Idea's canvas. Every section is optional while drafting." }, "CanvasAutosave": { "type": "object", "properties": { "version": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "document": { "type": "object", "properties": { "value_map": { "type": "object", "properties": { "products_services": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 } }, "required": [ "id", "text" ], "additionalProperties": false } }, "pain_relievers": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 }, "pain_id": { "type": "string", "maxLength": 80 } }, "required": [ "id", "text", "pain_id" ], "additionalProperties": false } }, "gain_creators": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 }, "gain_id": { "type": "string", "maxLength": 80 } }, "required": [ "id", "text", "gain_id" ], "additionalProperties": false } } }, "additionalProperties": false }, "customer_profile": { "type": "object", "properties": { "segment_name": { "type": "string", "maxLength": 200 }, "segment_description": { "type": "string", "maxLength": 4000 }, "jobs": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 }, "tag": { "type": "string", "enum": [ "functional", "social", "emotional" ] } }, "required": [ "id", "text", "tag" ], "additionalProperties": false } }, "pains": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 } }, "required": [ "id", "text" ], "additionalProperties": false } }, "gains": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "text": { "type": "string", "maxLength": 4000 } }, "required": [ "id", "text" ], "additionalProperties": false } }, "competitors": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "maxLength": 200 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "id", "name" ], "additionalProperties": false } } }, "additionalProperties": false }, "gtm": { "type": "object", "properties": { "value_prop_one_liner": { "type": "string", "maxLength": 500 }, "differentiation_claim": { "type": "string", "maxLength": 2000 }, "primary_channel": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "direct", "partner", "content", "outbound", "community", "product_led", "marketplace", "other" ] }, "detail": { "type": "string", "maxLength": 500 } }, "required": [ "kind", "detail" ], "additionalProperties": false }, "proof_needed": { "type": "string", "maxLength": 2000 } }, "additionalProperties": false }, "pricing": { "type": "object", "properties": { "pricing_motion": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "subscription", "usage", "project", "marketplace", "other" ] }, "detail": { "type": "string", "maxLength": 500 } }, "required": [ "kind", "detail" ], "additionalProperties": false }, "comps": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "maxLength": 200 }, "model": { "type": "string", "maxLength": 200 }, "published_price_band": { "type": "string", "maxLength": 200 }, "source_url": { "type": "string", "maxLength": 2000 }, "checked_date": { "type": "string" } }, "required": [ "id", "name", "model", "published_price_band", "source_url", "checked_date" ], "additionalProperties": false } }, "tiers": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "name": { "type": "string", "maxLength": 200 }, "who": { "type": "string", "maxLength": 500 }, "price": { "type": "string", "maxLength": 200 }, "included": { "type": "string", "maxLength": 2000 } }, "required": [ "id", "name", "who", "price", "included" ], "additionalProperties": false } }, "recommended_band": { "type": "object", "properties": { "low": { "type": "number", "minimum": 0 }, "high": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "minLength": 1, "maxLength": 8 }, "unit": { "type": "string", "enum": [ "seat", "workspace", "session", "usage" ] } }, "required": [ "low", "high", "currency", "unit" ], "additionalProperties": false }, "rationale": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 4000 }, "field_id": { "type": "string", "maxLength": 200 } }, "required": [ "text", "field_id" ], "additionalProperties": false } }, "additionalProperties": false }, "outputs": { "type": "object", "properties": { "names": { "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "positioning": { "type": "object", "properties": { "primary": { "type": "string", "maxLength": 500 }, "alternate": { "type": "string", "maxLength": 500 } }, "required": [ "primary", "alternate" ], "additionalProperties": false }, "pitches": { "type": "object", "properties": { "tagline_5s": { "type": "string", "maxLength": 280 }, "pitch_30s": { "type": "string", "maxLength": 2000 } }, "required": [ "tagline_5s", "pitch_30s" ], "additionalProperties": false }, "buyer_packs": { "type": "object", "properties": { "ceo": { "maxItems": 30, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 80 }, "question": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "id", "question" ], "additionalProperties": false } } }, "required": [ "ceo" ], "additionalProperties": false }, "implied_capabilities": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 300 }, "source_field_id": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "text", "source_field_id" ], "additionalProperties": false } } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": [ "version", "document" ], "additionalProperties": false }, "Canvas": { "type": "object", "properties": { "session_id": { "type": "string" }, "version": { "type": "integer" }, "updated_at": { "type": "string", "format": "date-time" }, "document": { "$ref": "#/components/schemas/CanvasDraft" }, "sample": { "type": "boolean" } }, "required": [ "session_id", "version", "updated_at", "document" ] }, "InterviewTurnRequest": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 100000 }, "assume_rest": { "type": "boolean" } }, "additionalProperties": false, "description": "Send `message` (free text up to 100,000 characters), or `assume_rest: true`, or both." }, "Interview": { "type": "object", "properties": { "session_id": { "type": "string" }, "version": { "type": "integer", "description": "Canvas version after this turn." }, "updated_at": { "type": "string", "format": "date-time" }, "mode": { "description": "`model` when Claude read the message, `deterministic` when it did not. Null on GET.", "enum": [ "model", "deterministic", null ] }, "model": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallback_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the model did not answer. A code, never content." }, "understood": { "type": "array", "items": { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "stage": { "type": "string" }, "value": { "type": "string" }, "assumed": { "type": "boolean" } }, "required": [ "slot", "stage", "value", "assumed" ] } }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "slot": { "anyOf": [ { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, { "type": "null" } ] }, "code": { "type": "string" } }, "required": [ "slot", "code" ] } }, "hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Required slots still empty." }, "questions": { "type": "array", "maxItems": 3, "description": "Follow-up questions to put to the person.", "items": { "type": "object", "properties": { "slot": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "text": { "type": "string" } }, "required": [ "slot", "text" ] } }, "ready": { "type": "boolean", "description": "True when the Idea can be forged." }, "gate_missing": { "type": "array", "items": { "type": "string" }, "description": "Canvas fields the forge gate still needs." }, "assumed": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots holding a value Finery assumed." }, "document": { "$ref": "#/components/schemas/CanvasDraft" } }, "required": [ "session_id", "version", "updated_at", "mode", "model", "fallback_reason", "understood", "rejected", "hint", "missing", "questions", "ready", "gate_missing", "assumed", "document" ] }, "Ready": { "type": "object", "properties": { "ready": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "Canvas field paths still missing." } }, "required": [ "ready", "missing" ] }, "Confirmation": { "type": "object", "properties": { "confirmed": { "type": "boolean" }, "stale": { "type": "boolean" }, "canvas_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "forge_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "confirmed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "confirmed", "stale", "canvas_version", "forge_version", "confirmed_at" ] }, "Snapshot": { "type": "object", "properties": { "session_id": { "type": "string" }, "forge_version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "document": { "$ref": "#/components/schemas/CanvasDraft" } }, "required": [ "session_id", "forge_version", "created_at", "document" ] }, "Checks": { "type": "object", "properties": { "checked_at": { "type": "string", "maxLength": 40 }, "notice": { "type": "string", "maxLength": 400 }, "checks": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "domains", "trademarks", "existing", "demand", "uk_companies" ] }, "title": { "type": "string", "maxLength": 80 }, "status": { "type": "string", "enum": [ "found", "clear", "not_checked" ] }, "finding": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "reason": { "anyOf": [ { "type": "string", "maxLength": 400 }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "url": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "name", "url" ], "additionalProperties": false }, { "type": "null" } ] }, "checked_at": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "domains": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string", "maxLength": 80 }, "result": { "type": "string", "enum": [ "registered", "unavailable", "appears_unregistered", "not_checked" ] }, "reason": { "type": "string", "maxLength": 400 } }, "required": [ "domain", "result" ], "additionalProperties": false } }, "trademarks": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "identical": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "similar": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "marks": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "office": { "type": "string", "maxLength": 4 }, "number": { "type": "string", "maxLength": 40 }, "name": { "type": "string", "maxLength": 200 }, "status": { "type": "string", "maxLength": 40 }, "nice_classes": { "maxItems": 45, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 45 } }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "office", "number", "name", "status", "nice_classes", "url" ], "additionalProperties": false } }, "not_checked": { "type": "string", "maxLength": 400 } }, "required": [ "name", "identical", "similar", "marks" ], "additionalProperties": false } }, "existing": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "claim": { "type": "string", "maxLength": 400 }, "url": { "type": "string", "maxLength": 2000 }, "title": { "type": "string", "maxLength": 200 } }, "required": [ "claim", "url", "title" ], "additionalProperties": false } }, "demand": { "type": "object", "properties": { "location": { "type": "string", "maxLength": 80 }, "keywords": { "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "keyword": { "type": "string", "maxLength": 80 }, "interest": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 100 }, { "type": "null" } ] } }, "required": [ "keyword", "interest" ], "additionalProperties": false } } }, "required": [ "location", "keywords" ], "additionalProperties": false }, "companies": { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "matches": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "number": { "type": "string", "maxLength": 8 }, "dissolved": { "type": "boolean" }, "url": { "type": "string", "maxLength": 2000 } }, "required": [ "name", "number", "dissolved", "url" ], "additionalProperties": false } }, "reason": { "type": "string", "maxLength": 400 } }, "required": [ "name", "matches" ], "additionalProperties": false } } }, "required": [ "id", "title", "status", "finding", "reason", "source", "checked_at" ], "additionalProperties": false } } }, "required": [ "checked_at", "notice", "checks" ], "additionalProperties": false }, "Bundle": { "type": "object", "properties": { "session_id": { "type": "string" }, "stale": { "type": "boolean", "description": "True when the canvas changed after these Results were forged." }, "confirmed_canvas_version": { "type": "integer" }, "confirmed_forge_version": { "type": "integer" }, "mock": { "type": "boolean", "description": "True when any block is sample text rather than a real model answer." }, "mock_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blocks_provenance": { "type": "array", "description": "Per-block real or sample outcome. Absent on versions stored before provenance existed.", "items": { "type": "object", "properties": { "block": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack" ] }, "real": { "type": "boolean" }, "model": { "type": "string" }, "reason": { "type": "string" }, "status_class": { "type": "string", "enum": [ "4xx", "5xx" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "repaired": { "type": "boolean" } }, "required": [ "block", "real" ] } }, "checks": { "$ref": "#/components/schemas/Checks", "description": "Launch Checks. Absent on Results forged before Checks existed." }, "blocks": { "type": "object", "properties": { "names": { "type": "object", "properties": { "version": { "type": "integer" }, "canonical": { "type": "string", "description": "Canonical JSON of the payload." }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "stale": { "type": "boolean" }, "payload": { "type": "object", "properties": { "options": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "keyword": { "type": "string" } }, "required": [ "name", "keyword" ] } } }, "required": [ "options" ] }, "assumed_inputs": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots Finery assumed in the canvas this block was written from. Absent when none." } }, "required": [ "version", "canonical", "updated_at", "canvas_version", "forge_version", "stale", "payload" ] }, "positioning": { "type": "object", "properties": { "version": { "type": "integer" }, "canonical": { "type": "string", "description": "Canonical JSON of the payload." }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "stale": { "type": "boolean" }, "payload": { "type": "object", "properties": { "primary": { "type": "string" }, "alternate": { "type": "string" } }, "required": [ "primary", "alternate" ] }, "assumed_inputs": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots Finery assumed in the canvas this block was written from. Absent when none." } }, "required": [ "version", "canonical", "updated_at", "canvas_version", "forge_version", "stale", "payload" ] }, "pitch": { "type": "object", "properties": { "version": { "type": "integer" }, "canonical": { "type": "string", "description": "Canonical JSON of the payload." }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "stale": { "type": "boolean" }, "payload": { "type": "object", "properties": { "pitch30": { "type": "string" }, "tagline5": { "type": "string" }, "word_count": { "type": "integer" } }, "required": [ "pitch30", "tagline5", "word_count" ] }, "assumed_inputs": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots Finery assumed in the canvas this block was written from. Absent when none." } }, "required": [ "version", "canonical", "updated_at", "canvas_version", "forge_version", "stale", "payload" ] }, "ceo-pack": { "type": "object", "properties": { "version": { "type": "integer" }, "canonical": { "type": "string", "description": "Canonical JSON of the payload." }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "stale": { "type": "boolean" }, "payload": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "depends_on": { "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "trace": { "type": "object", "properties": { "path": { "type": "string" }, "value": { "type": "string" } }, "required": [ "path", "value" ] } }, "required": [ "text", "trace" ] }, "minItems": 3, "maxItems": 3 }, "blank": { "const": "" } }, "required": [ "id", "question", "depends_on", "answers", "blank" ] } }, "hidden": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "depends_on": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "question", "depends_on", "reason" ] } }, "shortfall": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "questions", "hidden", "shortfall" ] }, "assumed_inputs": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots Finery assumed in the canvas this block was written from. Absent when none." } }, "required": [ "version", "canonical", "updated_at", "canvas_version", "forge_version", "stale", "payload" ] }, "cfo-pack": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer" }, "canonical": { "type": "string", "description": "Canonical JSON of the payload." }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "stale": { "type": "boolean" }, "payload": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "depends_on": { "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "trace": { "type": "object", "properties": { "path": { "type": "string" }, "value": { "type": "string" } }, "required": [ "path", "value" ] } }, "required": [ "text", "trace" ] }, "minItems": 3, "maxItems": 3 }, "blank": { "const": "" } }, "required": [ "id", "question", "depends_on", "answers", "blank" ] } }, "hidden": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "depends_on": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "question", "depends_on", "reason" ] } }, "shortfall": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "questions", "hidden", "shortfall" ] }, "assumed_inputs": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots Finery assumed in the canvas this block was written from. Absent when none." } }, "required": [ "version", "canonical", "updated_at", "canvas_version", "forge_version", "stale", "payload" ] }, { "type": "null" } ] }, "tech-pack": { "anyOf": [ { "type": "object", "properties": { "version": { "type": "integer" }, "canonical": { "type": "string", "description": "Canonical JSON of the payload." }, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "stale": { "type": "boolean" }, "payload": { "type": "object", "properties": { "questions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "depends_on": { "type": "string" }, "answers": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "trace": { "type": "object", "properties": { "path": { "type": "string" }, "value": { "type": "string" } }, "required": [ "path", "value" ] } }, "required": [ "text", "trace" ] }, "minItems": 3, "maxItems": 3 }, "blank": { "const": "" } }, "required": [ "id", "question", "depends_on", "answers", "blank" ] } }, "hidden": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "depends_on": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "id", "question", "depends_on", "reason" ] } }, "shortfall": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "questions", "hidden", "shortfall" ] }, "assumed_inputs": { "type": "array", "items": { "type": "string", "enum": [ "product", "one_liner", "segment_name", "segment_description", "secondary", "functional", "emotional", "pain", "reliever", "gain", "creator", "competitor", "why_us", "channel", "proof", "motion", "comp", "tier", "band", "rationale" ] }, "description": "Slots Finery assumed in the canvas this block was written from. Absent when none." } }, "required": [ "version", "canonical", "updated_at", "canvas_version", "forge_version", "stale", "payload" ] }, { "type": "null" } ] } }, "required": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack" ] } }, "required": [ "session_id", "stale", "confirmed_canvas_version", "confirmed_forge_version", "mock", "mock_label", "blocks" ] }, "BundleVersionList": { "type": "object", "properties": { "session_id": { "type": "string" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "forge_version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "mock": { "type": "boolean" }, "mock_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blocks_provenance": { "type": "array", "description": "Per-block real or sample outcome. Absent on versions stored before provenance existed.", "items": { "type": "object", "properties": { "block": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack" ] }, "real": { "type": "boolean" }, "model": { "type": "string" }, "reason": { "type": "string" }, "status_class": { "type": "string", "enum": [ "4xx", "5xx" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "repaired": { "type": "boolean" } }, "required": [ "block", "real" ] } } }, "required": [ "forge_version", "created_at", "mock", "mock_label" ] } } }, "required": [ "session_id", "versions" ] }, "BundleVersion": { "type": "object", "properties": { "session_id": { "type": "string" }, "forge_version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "document": { "$ref": "#/components/schemas/CanvasDraft" }, "blocks": { "type": "object", "properties": { "names": { "type": "object", "properties": { "version": { "type": "integer" }, "payload": {}, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" } }, "required": [ "version", "payload", "updated_at", "canvas_version", "forge_version" ] }, "positioning": { "type": "object", "properties": { "version": { "type": "integer" }, "payload": {}, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" } }, "required": [ "version", "payload", "updated_at", "canvas_version", "forge_version" ] }, "pitch": { "type": "object", "properties": { "version": { "type": "integer" }, "payload": {}, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" } }, "required": [ "version", "payload", "updated_at", "canvas_version", "forge_version" ] }, "ceo-pack": { "type": "object", "properties": { "version": { "type": "integer" }, "payload": {}, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" } }, "required": [ "version", "payload", "updated_at", "canvas_version", "forge_version" ] }, "cfo-pack": { "type": "object", "properties": { "version": { "type": "integer" }, "payload": {}, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" } }, "required": [ "version", "payload", "updated_at", "canvas_version", "forge_version" ] }, "tech-pack": { "type": "object", "properties": { "version": { "type": "integer" }, "payload": {}, "updated_at": { "type": "string", "format": "date-time" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" } }, "required": [ "version", "payload", "updated_at", "canvas_version", "forge_version" ] } }, "required": [ "names", "positioning", "pitch", "ceo-pack" ] }, "selections": { "$ref": "#/components/schemas/Selection" }, "mock": { "type": "boolean" }, "mock_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "blocks_provenance": { "type": "array", "description": "Per-block real or sample outcome. Absent on versions stored before provenance existed.", "items": { "type": "object", "properties": { "block": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack" ] }, "real": { "type": "boolean" }, "model": { "type": "string" }, "reason": { "type": "string" }, "status_class": { "type": "string", "enum": [ "4xx", "5xx" ] }, "paths": { "type": "array", "items": { "type": "string" } }, "repaired": { "type": "boolean" } }, "required": [ "block", "real" ] } } }, "required": [ "session_id", "forge_version", "created_at", "document", "blocks", "selections", "mock", "mock_label" ] }, "BundleDiff": { "type": "object", "properties": { "session_id": { "type": "string" }, "from": { "type": "integer" }, "to": { "type": "integer" }, "from_mock": { "type": "boolean" }, "to_mock": { "type": "boolean" }, "from_mock_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "to_mock_label": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "changes": { "type": "array", "items": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "canvas", "output", "selection" ] }, "path": { "type": "string" }, "kind": { "type": "string", "enum": [ "added", "removed", "changed" ] }, "before": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "after": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "same", "added", "removed" ] }, "text": { "type": "string" } }, "required": [ "kind", "text" ] } }, { "type": "null" } ] }, "textLayout": { "enum": [ "inline", "lines", null ] } }, "required": [ "scope", "path", "kind", "before", "after", "text", "textLayout" ] } } }, "required": [ "session_id", "from", "to", "from_mock", "to_mock", "from_mock_label", "to_mock_label", "changes" ] }, "RestoreRequest": { "type": "object", "properties": { "forge_version": { "type": "integer", "minimum": 1, "description": "The bundle version to copy into a new version." }, "undo": { "type": "object", "properties": { "blocks": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack" ] } } }, "required": [ "blocks" ], "description": "Undo a block regenerate: name the blocks it just replaced. Omit for a plain restore." } }, "required": [ "forge_version" ] }, "Selection": { "type": "object", "properties": { "names": { "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "positioning": { "anyOf": [ { "type": "string", "const": "primary" }, { "type": "string", "const": "alternate" }, { "type": "null" } ] }, "pitch": { "type": "boolean" }, "answers": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "choice": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "string", "const": "blank" } ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "question_id", "choice" ], "additionalProperties": false } }, "cfo_answers": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "choice": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "string", "const": "blank" } ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "question_id", "choice" ], "additionalProperties": false } }, "tech_answers": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "choice": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "string", "const": "blank" } ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "question_id", "choice" ], "additionalProperties": false } } }, "required": [ "names", "positioning", "pitch", "answers", "cfo_answers", "tech_answers" ], "additionalProperties": false }, "SelectionRequest": { "type": "object", "properties": { "names": { "maxItems": 3, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 120 } }, "positioning": { "anyOf": [ { "type": "string", "const": "primary" }, { "type": "string", "const": "alternate" }, { "type": "null" } ] }, "pitch": { "type": "boolean" }, "answers": { "maxItems": 10, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "choice": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "string", "const": "blank" } ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "question_id", "choice" ], "additionalProperties": false } }, "cfo_answers": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "choice": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "string", "const": "blank" } ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "question_id", "choice" ], "additionalProperties": false } }, "tech_answers": { "default": [], "maxItems": 3, "type": "array", "items": { "type": "object", "properties": { "question_id": { "type": "string", "minLength": 1, "maxLength": 80 }, "choice": { "anyOf": [ { "type": "number", "const": 0 }, { "type": "number", "const": 1 }, { "type": "number", "const": 2 }, { "type": "string", "const": "blank" } ] }, "text": { "type": "string", "maxLength": 2000 } }, "required": [ "question_id", "choice" ], "additionalProperties": false } } }, "required": [ "names", "positioning", "pitch", "answers" ], "additionalProperties": false }, "SelectionView": { "type": "object", "properties": { "valid": { "type": "boolean" }, "invalidated": { "type": "boolean" }, "selection": { "$ref": "#/components/schemas/Selection" } }, "required": [ "valid", "invalidated", "selection" ] }, "Comment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "idea_id": { "type": "string" }, "section": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack", "checks" ], "description": "The section of the Results the comment is on: a block id, or `checks`." }, "body": { "type": "string", "description": "Plain text." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Equal to `created_at` until the comment is edited." } }, "required": [ "id", "idea_id", "section", "body", "created_at", "updated_at" ] }, "CommentList": { "type": "object", "properties": { "idea_id": { "type": "string" }, "comments": { "type": "array", "items": { "$ref": "#/components/schemas/Comment" }, "description": "Oldest first." } }, "required": [ "idea_id", "comments" ] }, "CommentCreateRequest": { "type": "object", "properties": { "section": { "type": "string", "enum": [ "names", "positioning", "pitch", "ceo-pack", "cfo-pack", "tech-pack", "checks" ] }, "body": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "section", "body" ], "additionalProperties": false }, "CommentUpdateRequest": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "body" ], "additionalProperties": false }, "Export": { "type": "object", "properties": { "session_id": { "type": "string" }, "canvas_version": { "type": "integer" }, "confirmed_version": { "type": "integer" }, "bundle_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "generated_at": { "type": "string", "format": "date-time" }, "brief_generated_at": { "type": "string", "format": "date-time" }, "sample": { "type": "boolean" }, "mock": { "type": "boolean" }, "mock_label": { "type": "string" }, "model_label": { "type": "string" }, "blocks_provenance": { "type": "array", "items": { "type": "object" } }, "markdown": { "type": "string", "description": "The brief as Markdown." }, "linear": { "type": "string", "description": "The same brief laid out for a Linear issue." } }, "required": [ "session_id", "canvas_version", "confirmed_version", "bundle_version", "generated_at", "sample", "mock", "markdown", "linear" ] }, "OpportunitySettings": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false }, "OpportunityDecision": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "accept", "reject" ] } }, "required": [ "decision" ], "additionalProperties": false }, "OpportunityList": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "stale": { "type": "boolean" }, "confirmed_canvas_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "confirmed_forge_version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "opportunities": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "run_id": { "type": "string" }, "position": { "type": "integer" }, "canvas_version": { "type": "integer" }, "forge_version": { "type": "integer" }, "link": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "pain", "job" ] }, "id": { "type": "string" } }, "required": [ "kind", "id" ] }, "segment": { "type": "string" }, "title": { "type": "string" }, "summary": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending", "accepted", "rejected" ] }, "decided_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" }, "source": { "const": "mock" }, "label": { "type": "string" }, "stale": { "type": "boolean" } }, "required": [ "id", "run_id", "position", "canvas_version", "forge_version", "link", "segment", "title", "summary", "tags", "status", "decided_at", "created_at", "source", "label", "stale" ] } }, "omitted": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ] } } }, "required": [ "enabled", "stale", "confirmed_canvas_version", "confirmed_forge_version", "opportunities", "omitted", "failures" ] }, "Health": { "type": "object", "properties": { "ok": { "const": true }, "service": { "const": "finery" } }, "required": [ "ok", "service" ] } } } }