> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowyte.com/llms.txt > Use this file to discover all available pages before exploring further. # Edit a variable annotation > Edits the note or type hint on an existing variable annotation (only the fields you send change). Returns 404 if the name has no annotation. The annotation carries no runtime meaning. ## OpenAPI ````yaml /openapi.yaml patch /agents/{agentId}/variables/{name} openapi: 3.1.0 info: title: Flowyte V2 Control-Plane REST API version: 1.0.0 description: >- The single REST API for the Flowyte platform (base path `/api/v1`). Authenticate every request with a secret API key — `Authorization: Bearer flowyte_sk_…` — and each operation lists the scope the key must hold. Successful responses use the `ApiResponse` envelope; list responses use cursor-based `PaginatedResponse`. Errors are RFC 9457 problem+json. Streaming endpoints return Server-Sent Events (`event:\ndata:\n\n`, terminating with `event: done`). contact: name: Flowyte Platform license: name: Proprietary servers: - url: /api/v1 description: Flowyte control-plane (versioned URI; additive in v1). security: - apiKey: [] tags: - name: Agents description: The single user-facing entity. - name: Skills description: > Agent capabilities / tools. A skill is ONE atomic action — typically a single API call the agent makes in one step (look up an order, create a record, send a message, transfer the call). Use a skill when the task is a single step. When a task needs several details gathered across turns BEFORE acting, build a Playbook (which gathers the inputs and then calls skills) — see the Playbooks tag. - name: Integrations description: Native OAuth integrations. - name: Knowledge description: RAG knowledge sources & preview. - name: Playbooks description: > Multi-turn conversation scripts — a node graph (gather → confirm → branch) the agent follows to collect several inputs IN ORDER across turns before acting. Build a playbook when a single skill call isn't enough because the agent must gather MANY details first, or run a SEQUENCE of skills, before it can finish (e.g. take a full service request: gather the problem, address, and time, confirm, THEN file it; qualify a lead; a multi-step intake). A playbook does NOT call an integration itself — it owns the conversation and holds the state across turns; the actual action is performed by the SKILL(s) it gathers the inputs for. So a playbook ORCHESTRATES skills. Rule of thumb — one API call → a Skill; "gather N things in order, then submit" → a Playbook that drives the conversation and calls the skill(s) at the end. - name: Variables description: > The agent-wide interaction-variable registry (B.4b) — DERIVED at read time from the agent's playbooks and skills (collect slots, skill output bindings, {var} placeholders) and merged with a thin annotation overlay (notes, declared type hints, manual declarations). Read-only observation, NEVER a gate: it never validates a reference and never affects authoring, publish, or runtime behaviour. - name: Guardrails description: Deterministic guardrail policies & caller verification. - name: Numbers description: Phone numbers / DIDs. - name: Test description: Test, simulate, talk-token, probe. - name: Observe description: Post-call analytics, conversations, receipts, transcripts. - name: Billing description: Plans, wallet, usage, fixed phrases. - name: Voices description: Voice catalog. - name: Webhooks description: Webhook endpoints & deliveries. - name: AuditLogs description: API/key activity logs. - name: Chat description: Chat channel — sessions, messages, OpenAI-compatible, widget. - name: PublishableKeys description: Browser-safe, one-agent publishable keys. - name: Widget description: Embed widget config + snippet. - name: Uploads description: Multipart file uploads backing file_id params - name: Meta description: Platform metadata (language/SKU/tier capabilities). paths: /agents/{agentId}/variables/{name}: parameters: - $ref: '#/components/parameters/AgentIdPathScoped' - name: name in: path required: true schema: type: string description: >- The variable name (a case-sensitive identifier matching ^[a-zA-Z_][a-zA-Z0-9_]*$). patch: tags: - Variables summary: Edit a variable annotation description: >- Edits the note or type hint on an existing variable annotation (only the fields you send change). Returns 404 if the name has no annotation. The annotation carries no runtime meaning. operationId: updateVariable requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/VariableAnnotationUpdate' responses: '200': description: The updated variable. content: application/json: schema: $ref: '#/components/schemas/ApiResponse_Variable' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/Unprocessable' security: - apiKey: - playbooks:write components: parameters: AgentIdPathScoped: name: agentId in: path required: true schema: type: string schemas: VariableAnnotationUpdate: type: object description: >- Partial edit of an existing variable annotation — only the fields sent are changed. properties: note: type: string type: type: string ApiResponse_Variable: allOf: - $ref: '#/components/schemas/ApiResponseBase' - type: object required: - data properties: data: $ref: '#/components/schemas/Variable' ApiResponseBase: type: object required: - success properties: success: type: boolean message: type: string errors: type: array items: type: object required: - field - message properties: field: type: string message: type: string Variable: type: object description: >- A merged interaction variable: the DERIVED registry (scanned from playbooks + skills) unioned with the per-agent annotation overlay. `source`, `deletable`, `producedBy`, and `consumedBy` are computed from the scan; `note`, `type`, and `updatedAt` come from the annotation. `type` is an OPTIONAL, nullable hint that is NEVER enforced. required: - name - source - producedBy - consumedBy - note - deletable properties: name: type: string description: The variable name (case-sensitive identifier). source: type: string description: derived (graph-only) | declared (annotation-only) | both. enum: - derived - declared - both type: type: - string - 'null' description: An optional, never-enforced type hint from the annotation. producedBy: type: array description: The deduped set of origins that PRODUCE this variable. items: $ref: '#/components/schemas/VariableOrigin' consumedBy: type: array description: The deduped set of origins that CONSUME this variable. items: $ref: '#/components/schemas/VariableOrigin' note: type: string description: The annotation note (empty when there is no annotation). deletable: type: boolean description: >- true only when the variable has NO producers AND NO consumers (a purely-declared annotation). A still-referenced name reappears as pure-derived even if its annotation is dropped, so it is not deletable. updatedAt: type: string format: date-time description: >- When the annotation was last edited (omitted when there is no annotation). ProblemDetails: description: RFC 9457 problem+json. type: object properties: type: type: string format: uri default: about:blank title: type: string status: type: integer detail: type: string instance: type: string code: type: string errors: type: array items: type: object properties: field: type: string message: type: string VariableOrigin: type: object description: >- One producer or consumer of a variable — WHERE (ref) and HOW (kind) it appears. required: - kind - ref properties: kind: type: string description: >- The mechanism this origin represents. Producers: collect (a playbook collect slot), skill_output (a skill output binding). Consumers: message (a {var} in a message), binding (a {var} in a skill node's args), branch (a slot a branch routes on), skill_config (a {var} in a standalone skill's config). enum: - collect - skill_output - message - binding - branch - skill_config ref: type: string description: >- A human-readable location, e.g. "Book a visit · Collect" or "Skill send_email". responses: NotFound: description: Resource not found in org scope. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' Unprocessable: description: Semantically invalid (e.g. language not in SKU's STT set). content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' securitySchemes: apiKey: type: oauth2 description: > Flowyte secret API key (`Authorization: Bearer flowyte_sk_live_…`). Scope-gated; is scoped to your organization — a key can never reach another tenant. The listed scopes in each operation's `apiKey` requirement are the scopes that key must hold. The `tokenUrl` is nominal: keys are minted in the dashboard. flows: clientCredentials: tokenUrl: /api/v1/api-keys scopes: agents:read: Read agents. agents:write: Create/update/delete agents, publish, rollback. knowledge:read: Read knowledge sources & preview. knowledge:write: Add/remove knowledge sources, uploads. skills:read: Read skills & skill-types. skills:write: Create/update/delete skills. playbooks:read: Read playbooks & graphs. playbooks:write: Create/update/delete playbooks & graphs. guardrails:read: Read guardrail policies & caller-verification. guardrails:write: Update guardrail policies & caller-verification. numbers:read: Read phone numbers / search availability. numbers:write: Purchase / assign / release numbers. sms:read: Read the org's SMS (10DLC) registration status and numbers. sms:write: Save/submit the 10DLC registration and toggle numbers for SMS. outbound:read: Read outbound contact lists and campaigns. outbound:write: >- Create/import contact lists, create/launch/pause/resume/cancel outbound campaigns, and enqueue single outbound calls. integrations:read: Read connected native integrations (status only — never tokens). integrations:write: Discover schemas, set data scoping, and disconnect a connection. integrations:connect: >- Connect a data source (submit credentials / begin OAuth) — a SEPARATE, higher-privilege scope because connecting INGESTS credentials and opens a new egress path; a discover/scope/author key need not carry it. calls:read: Read conversations, receipts, transcripts, analytics. analytics:read: >- Read the Observe history list, per-agent analytics (the answer-rate summary), and the raw knowledge-gap list. analytics:write: >- Curate knowledge gaps (dismiss / mark in-progress). [M4 — reserved] billing:read: Read plans, wallet, usage. audit:read: Read API/key activity logs. webhooks:write: Manage webhook endpoints. keys:write: Manage secret API keys. chat:read: Read chat sessions & messages. chat:write: Create chat sessions & send messages (server-side). widgets:read: Read widget config & embed snippet. widgets:write: Update widget config. pubkeys:read: Read publishable keys. pubkeys:write: Manage publishable keys. ````