> ## Documentation Index > Fetch the complete documentation index at: https://docs.findtempo.co/llms.txt > Use this file to discover all available pages before exploring further. # Generate a canvas document — async job, poll by run_id > Trigger a canvas generation job against a deal universe: an anchored canonical subject, a GIVEN set, OR a structured filter (the same automation FilterExpression). A generate call always produces exactly one document over the resolved deal set — a caller wanting one document per deal makes N independent calls and owns batching and partial failures. Integrator notes: - **Always async.** The job runs in the background and this returns `202` with `run_id` — poll `GET /api/v1/canvas/generate/{run_id}` for the result. - **Actor scoping.** A bare API key is an **org principal**: the deal universe is your organization's full book, matching what the query surface serves the same key. Pass `X-Acting-User: ` to run the request as a specific member instead — the deal universe then narrows to the deals that member can see (their own book), and the value must name a real member of your org, or the request is rejected (`403`). - **Private templates.** A canvas published with `private` visibility is generable only by its owner: name the owner in `X-Acting-User`, or have the owner set the canvas's visibility to public (org-wide) in Dealbrain. Any other acting user gets a `403` naming the fix. - **Selector.** Pass exactly one of `subject`, `deal_ids`, or `filter`. `subject` carries the canonical selector shape and can anchor generation to one deal or meeting; it can also carry canonical deal IDs or a structured filter. `deal_ids` and `filter` are the backward-compatible top-level forms. - **Chip recognition.** Before the job is enqueued, every variable chip the canvas template declares is classified against the canvas chip catalog — the same catalog the canvas editor's chip picker offers: identity values (`current_date`, `current_datetime`, `user_name`, `seller_profile`), organization playbook rails (`company_context`, `house_rules`, …), period chips (resolve when the request carries a `period`, otherwise render unresolved), deal-field chips from your CRM field catalog (plus friendly aliases like `deal_name`/`stage`), aggregate rollups (unconditional), the bound tool's contract chips, and your `template_options` keys. A chip the catalog does not recognize never blocks the run: it renders as "unknown" (prose) or its humanized name (generate instructions), is named in the trigger response's `warnings`, and is reported per document in `result.documents[].unrecognized`. Tool-contract chips (e.g. the meeting presets' `meeting_title`) are recognized vocabulary whose values you can supply via `template_options`. - **Warnings.** Unrecognized chips and `template_options` keys the template neither declares nor consumes through a declared chip are surfaced in the trigger response's `warnings` array — check it to catch chip and key typos. The draft-message preset consumes `recipient_name`/`recipient_role` when its `recipient_context` chip is declared, so those feeder keys do not warn in that case. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/canvas/generate openapi: 3.0.0 info: title: Tempo API description: >- The Tempo API gives you programmatic access to Deal Brain over HTTP. Authenticate with an API key passed as a Bearer token in the `Authorization` header. If you are building an AI agent rather than a traditional integration, the [MCP server](/integrations/mcp) exposes a richer surface and handles auth over OAuth. version: '1.0' contact: {} servers: - url: https://findtempo.co description: Production security: [] tags: [] paths: /api/v1/canvas/generate: post: tags: - Canvas Generation summary: Generate a canvas document — async job, poll by run_id description: >- Trigger a canvas generation job against a deal universe: an anchored canonical subject, a GIVEN set, OR a structured filter (the same automation FilterExpression). A generate call always produces exactly one document over the resolved deal set — a caller wanting one document per deal makes N independent calls and owns batching and partial failures. Integrator notes: - **Always async.** The job runs in the background and this returns `202` with `run_id` — poll `GET /api/v1/canvas/generate/{run_id}` for the result. - **Actor scoping.** A bare API key is an **org principal**: the deal universe is your organization's full book, matching what the query surface serves the same key. Pass `X-Acting-User: ` to run the request as a specific member instead — the deal universe then narrows to the deals that member can see (their own book), and the value must name a real member of your org, or the request is rejected (`403`). - **Private templates.** A canvas published with `private` visibility is generable only by its owner: name the owner in `X-Acting-User`, or have the owner set the canvas's visibility to public (org-wide) in Dealbrain. Any other acting user gets a `403` naming the fix. - **Selector.** Pass exactly one of `subject`, `deal_ids`, or `filter`. `subject` carries the canonical selector shape and can anchor generation to one deal or meeting; it can also carry canonical deal IDs or a structured filter. `deal_ids` and `filter` are the backward-compatible top-level forms. - **Chip recognition.** Before the job is enqueued, every variable chip the canvas template declares is classified against the canvas chip catalog — the same catalog the canvas editor's chip picker offers: identity values (`current_date`, `current_datetime`, `user_name`, `seller_profile`), organization playbook rails (`company_context`, `house_rules`, …), period chips (resolve when the request carries a `period`, otherwise render unresolved), deal-field chips from your CRM field catalog (plus friendly aliases like `deal_name`/`stage`), aggregate rollups (unconditional), the bound tool's contract chips, and your `template_options` keys. A chip the catalog does not recognize never blocks the run: it renders as "unknown" (prose) or its humanized name (generate instructions), is named in the trigger response's `warnings`, and is reported per document in `result.documents[].unrecognized`. Tool-contract chips (e.g. the meeting presets' `meeting_title`) are recognized vocabulary whose values you can supply via `template_options`. - **Warnings.** Unrecognized chips and `template_options` keys the template neither declares nor consumes through a declared chip are surfaced in the trigger response's `warnings` array — check it to catch chip and key typos. The draft-message preset consumes `recipient_name`/`recipient_role` when its `recipient_context` chip is declared, so those feeder keys do not warn in that case. operationId: CanvasGenerateController_generate_v1 parameters: - name: X-Acting-User in: header description: >- Scope the request to a specific member of your organization (user id or email). Defaults to the API key's default member. required: false schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - canvas_id description: Exactly one of `subject`, `deal_ids`, or `filter` is required. oneOf: - required: - subject - required: - deal_ids - required: - filter properties: canvas_id: type: string format: uuid description: The published canvas to generate from. deal_ids: type: array minItems: 1 items: type: string format: uuid description: >- An explicit deal set (provide this OR `subject` OR `filter`). subject: type: object description: >- Canonical generation selector. Provide this OR top-level `deal_ids` OR top-level `filter`. oneOf: - type: object additionalProperties: false required: - mode - runAnchor properties: mode: type: string enum: - anchor runAnchor: description: The single deal or meeting that anchors generation. oneOf: - type: object additionalProperties: false required: - type - id properties: type: type: string enum: - deal id: type: string minLength: 1 - type: object additionalProperties: false required: - type - id properties: type: type: string enum: - meeting id: type: string minLength: 1 expectedDealId: type: string minLength: 1 description: >- Optional assertion that the anchor resolves to this deal; it is not used to select a deal. - type: object additionalProperties: false required: - mode - dealIds properties: mode: type: string enum: - deal_ids dealIds: type: array items: type: string minLength: 1 minItems: 1 - type: object additionalProperties: false required: - mode - filter properties: mode: type: string enum: - filter filter: type: object description: A structured automation FilterExpression. filter: type: object description: >- A structured automation FilterExpression selecting the deal universe (provide this OR `subject` OR `deal_ids`). template_options: type: object additionalProperties: type: string description: >- Author/runtime chip values not derivable from the deals (e.g. period_label, target_amount, user_prompt). The draft-message preset reads recipient_name/recipient_role from here for its recipient_context chip. Keys the template neither declares nor consumes through a declared chip are accepted but echoed back as warnings. period: type: object description: >- Reporting-period spec; resolved to a concrete window for the change/movement lens. as_of: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Point-in-time anchor (YYYY-MM-DD). responses: '202': description: The job was enqueued; poll GET by run_id for the result. content: application/json: schema: type: object required: - run_id - status - result - error - created_at - completed_at properties: run_id: type: string status: type: string enum: - pending - running - completed - failed result: type: object nullable: true description: Present once status is completed. error: type: string nullable: true description: Present once status is failed. created_at: type: string completed_at: type: string nullable: true warnings: type: array items: type: string description: >- Trigger responses only: non-fatal request problems (unrecognized chips, template_options keys the template does not declare). '400': description: >- Invalid request body (unknown fields, malformed filter, over-cap fan-out, or no resolvable deals). '401': description: Missing or invalid API key. '403': description: >- X-Acting-User does not name a member of the caller's organization, or the canvas is a private template the acting user does not own. '404': description: >- No canvas with that id in the caller's organization, or it has no published version. '409': description: >- The published Canvas version predates immutable generation metadata; republish it before generating. security: - api-key: [] components: securitySchemes: api-key: type: apiKey in: header name: Authorization description: API key passed as Bearer token (e.g. "Bearer your-api-key") ````