{ "openapi": "3.0.3", "info": { "title": "Wavelength API", "version": "1.0.0", "description": "Wavelength turns calls, transcripts, and notes into editable process flow diagrams. Use this API to generate flows from text with AI, read and change flows, export them as Mermaid, SVG, draw.io, or JSON, find gaps, write summaries, and share public links. Authenticate with a Wavelength API key in the Authorization header: `Bearer wlk_...`. Make a personal key in Wavelength under Settings > API keys.", "contact": { "name": "Wavelength support", "email": "support@wavelengthflow.com", "url": "https://wavelengthflow.com/developers.html" }, "termsOfService": "https://wavelengthflow.com/terms" }, "externalDocs": { "url": "https://wavelengthflow.com/developers.html" }, "servers": [ { "url": "https://lnzcwfswvljbijqszxxn.supabase.co/functions/v1/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "AI" }, { "name": "Flows" }, { "name": "Sharing" }, { "name": "Account" }, { "name": "Organization" } ], "paths": { "/me": { "get": { "operationId": "getMe", "summary": "Get the current key", "description": "Returns the key, its scopes, and the person or organization it acts for. Works with every key.", "tags": [ "Account" ], "responses": { "200": { "description": "The key details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows": { "get": { "operationId": "listFlows", "summary": "List flows", "description": "Lists the flows the key can open, newest change first.", "tags": [ "Flows" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Start of the page. Use next_offset from the last page.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "updated_since", "in": "query", "description": "Only flows changed at or after this time (ISO 8601).", "schema": { "type": "string", "format": "date-time" } }, { "name": "team_id", "in": "query", "description": "Only flows of this team.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "A page of flows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "post": { "operationId": "createFlow", "summary": "Create a flow from nodes and edges", "description": "Makes a new flow from a graph that you send. Nodes without x and y are laid out for you.", "tags": [ "Flows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowInput" } } } }, "responses": { "201": { "description": "The saved flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/generate": { "post": { "operationId": "generateFlow", "summary": "Generate a flow from text with AI", "description": "Turns a transcript, call notes, or a plain description into a new process flow diagram. Counts against the plan of the key owner.", "tags": [ "AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "maxLength": 100000, "description": "The transcript, notes, or process description." }, "title": { "type": "string", "description": "Optional. Wavelength picks a title when empty." }, "direction": { "type": "string", "enum": [ "vertical", "horizontal" ], "default": "vertical" }, "team_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "The new flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/search": { "get": { "operationId": "searchFlows", "summary": "Search flows", "description": "Searches flow titles, steps, and transcripts.", "tags": [ "Flows" ], "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "The matching flows.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getFlow", "summary": "Get a flow", "description": "Returns one flow with its nodes, edges, transcript, and Mermaid code.", "tags": [ "Flows" ], "responses": { "200": { "description": "The flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "patch": { "operationId": "updateFlow", "summary": "Update a flow", "description": "Changes the fields that you send. Send graph_nodes and graph_edges together, because they replace the whole graph.", "tags": [ "Flows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/FlowInput" }, { "type": "object", "properties": { "snapshot": { "type": "boolean", "description": "Keep a version in the flow history." }, "version_label": { "type": "string" } } } ] } } } }, "responses": { "200": { "description": "The changed flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "deleteFlow", "summary": "Delete a flow", "tags": [ "Flows" ], "responses": { "200": { "description": "The flow is deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/edit": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "editFlowWithInstruction", "summary": "Edit a flow with an AI instruction", "description": "Changes the flow from a plain instruction, for example \"Add a manager approval before the refund\". Saves a version.", "tags": [ "AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "instruction" ], "properties": { "instruction": { "type": "string" } } } } } }, "responses": { "200": { "description": "The changed flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/notes": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "addNotesToFlow", "summary": "Add notes to a flow with AI", "description": "Adds new notes or transcript text. Wavelength reuses steps that are already on the diagram.", "tags": [ "AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string" } } } } } }, "responses": { "200": { "description": "The changed flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/duplicate": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "duplicateFlow", "summary": "Duplicate a flow", "tags": [ "Flows" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" } } } } } }, "responses": { "201": { "description": "The copy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlowResponse" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/export": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "exportFlow", "summary": "Export a flow", "description": "Exports the flow as Mermaid, SVG, draw.io, or JSON.", "tags": [ "Flows" ], "parameters": [ { "name": "format", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "mermaid", "svg", "drawio", "json" ] } } ], "responses": { "200": { "description": "The export.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/review": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "reviewFlow", "summary": "Find gaps in a flow", "description": "Finds steps with no connection, dead ends, decisions with one branch, unlabeled branches, steps with no owner, and AI-guessed links. Returns questions to ask on the next call. No AI cost.", "tags": [ "Flows" ], "responses": { "200": { "description": "The gaps and questions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Review" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/summaries": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "summarizeFlow", "summary": "Write a summary of a flow", "description": "overview returns summary and gaps. recaps returns customer_recap, handoff, and leadership. systems_in_scope returns each system with its inputs and outputs.", "tags": [ "AI" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "overview", "recaps", "systems_in_scope" ] } } } } } }, "responses": { "200": { "description": "The summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/flows/{id}/publish": { "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The flow ID (UUID).", "schema": { "type": "string", "format": "uuid" } } ], "post": { "operationId": "publishFlow", "summary": "Turn on the public link", "description": "Turns on the public read-only link and returns public_url.", "tags": [ "Sharing" ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "summary": { "type": "string" } } } } } }, "responses": { "200": { "description": "The public link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publish" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } }, "delete": { "operationId": "unpublishFlow", "summary": "Turn off the public link", "tags": [ "Sharing" ], "responses": { "200": { "description": "The link is off.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Publish" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/audit": { "get": { "operationId": "listAuditEvents", "summary": "List audit events", "description": "Organization keys with audit:read only. Newest first.", "tags": [ "Organization" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "before_id", "in": "query", "description": "Next page: next_before_id from the last page.", "schema": { "type": "integer" } }, { "name": "action", "in": "query", "schema": { "type": "string" }, "description": "Only this event type, for example flow_shared." }, { "name": "actor", "in": "query", "schema": { "type": "string" }, "description": "Only events whose actor email contains this text." }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditList" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/usage": { "get": { "operationId": "getUsage", "summary": "Get organization usage", "description": "Organization keys with usage:read only. Seats, totals, and one row per member.", "tags": [ "Organization" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } } ], "responses": { "200": { "description": "The usage report.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "wlk_ API key" } }, "responses": { "Error": { "description": "Error. Codes: bad_request, bad_graph, unauthorized, key_expired, save_failed, missing_scope, not_found, rate_limited, internal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Node": { "type": "object", "required": [ "label" ], "properties": { "id": { "type": "string", "description": "Unique in the flow. Default n1, n2." }, "type": { "type": "string", "enum": [ "start", "step", "decision", "data", "system", "actor", "end", "screen" ], "default": "step" }, "label": { "type": "string", "maxLength": 500 }, "owner": { "type": "string", "description": "Role or team that does the step. Used for swimlanes." }, "x": { "type": "number" }, "y": { "type": "number" } } }, "Edge": { "type": "object", "required": [ "source", "target" ], "properties": { "id": { "type": "string" }, "source": { "type": "string" }, "target": { "type": "string" }, "label": { "type": "string" } } }, "Flow": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "graph_nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" } }, "graph_edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" } }, "transcript": { "type": "string", "nullable": true }, "diagram_code": { "type": "string", "nullable": true }, "team_id": { "type": "string", "nullable": true }, "folder_id": { "type": "string", "nullable": true }, "is_public": { "type": "boolean" }, "owner": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "FlowInput": { "type": "object", "properties": { "title": { "type": "string" }, "graph_nodes": { "type": "array", "items": { "$ref": "#/components/schemas/Node" } }, "graph_edges": { "type": "array", "items": { "$ref": "#/components/schemas/Edge" } }, "transcript": { "type": "string" }, "diagram_code": { "type": "string" }, "team_id": { "type": "string", "format": "uuid" } } }, "FlowResponse": { "type": "object", "properties": { "flow": { "$ref": "#/components/schemas/Flow" } } }, "FlowList": { "type": "object", "properties": { "flows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "owner": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "team_id": { "type": "string", "nullable": true }, "folder_id": { "type": "string", "nullable": true }, "is_public": { "type": "boolean" } } } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true } } }, "SearchResult": { "type": "object", "additionalProperties": true }, "Export": { "type": "object", "additionalProperties": true }, "Review": { "type": "object", "additionalProperties": true }, "Summary": { "type": "object", "additionalProperties": true }, "Usage": { "type": "object", "additionalProperties": true }, "Me": { "type": "object", "additionalProperties": true }, "Publish": { "type": "object", "properties": { "public_url": { "type": "string" } }, "additionalProperties": true }, "Deleted": { "type": "object", "properties": { "deleted": { "type": "boolean" }, "id": { "type": "string" } } }, "AuditList": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "next_before_id": { "type": "integer", "nullable": true } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }