> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sidenet.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Preview agent prompt

> Resolves the agent's prompt blocks and renders them with the supplied `variables`, returning the final prompt plus a per-block breakdown: whether each block was included (and why not), what it rendered to, and which of its `{{variables}}` had no value. `version` selects which instructions to render — "draft" (default), a published version number, or a version id. Unresolvable block references are an error here (422) rather than being skipped, so you see problems before publishing. Variables rejected by the size/type limits come back in `droppedVariables`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agents/{id}/instructions/preview
openapi: 3.1.0
info:
  title: Sidenet API
  version: 1.0.0
  description: >-
    Sidenet HTTP endpoints exposed by the Sidenet Studio. All routes require an
    api key that can be generated through the studio in studio.sidenet.ai.
servers:
  - url: https://api.sidenet.ai
security:
  - bearerAuth: []
paths:
  /v1/agents/{id}/instructions/preview:
    post:
      tags:
        - Agents
      summary: Preview agent prompt
      description: >-
        Resolves the agent's prompt blocks and renders them with the supplied
        `variables`, returning the final prompt plus a per-block breakdown:
        whether each block was included (and why not), what it rendered to, and
        which of its `{{variables}}` had no value. `version` selects which
        instructions to render — "draft" (default), a published version number,
        or a version id. Unresolvable block references are an error here (422)
        rather than being skipped, so you see problems before publishing.
        Variables rejected by the size/type limits come back in
        `droppedVariables`.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            example: 6f1c0f4e-2b7a-4a51-9a2f-0c9d1b3e5a10
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                version:
                  oneOf:
                    - type: string
                    - type: integer
                  description: '"draft" (default), a version number, or a version id.'
                  example: draft
                variables:
                  type: object
                  additionalProperties: true
                  example:
                    locale: French
                    instance:
                      store_count: 12
      responses:
        '200':
          description: The rendered prompt, and what each block contributed
          content:
            application/json:
              schema:
                type: object
                properties:
                  authoredPrompt:
                    type: string
                    description: >-
                      The final system prompt: every included block rendered and
                      joined. This is the ORG's authored prompt only — the
                      platform blocks (tool guidance, approvals) are appended at
                      build time and are not shown here.
                  usesBlocks:
                    type: boolean
                    description: >-
                      False when the instructions are plain text with no block
                      references.
                  blocks:
                    type: array
                    description: One entry per block, in order, included or not.
                    items:
                      type: object
                      properties:
                        blockId:
                          type: string
                          format: uuid
                          nullable: true
                        blockVersionId:
                          type: string
                          format: uuid
                          nullable: true
                        name:
                          type: string
                          nullable: true
                        included:
                          type: boolean
                          description: >-
                            False when the block's display condition did not
                            match.
                        reason:
                          type: string
                          description: >-
                            Why it was left out. Present only when `included` is
                            false.
                        rendered:
                          type: string
                          description: >-
                            What this block rendered to. Empty when it was
                            excluded.
                        missingVariables:
                          type: array
                          description: '`{{variables}}` in this block that had no value.'
                          items:
                            type: string
                  droppedVariables:
                    type: array
                    description: >-
                      Variables you sent that were rejected by the size/type
                      limits, so they took no part in the render.
                    items:
                      type: string
              example:
                authoredPrompt: |-
                  You are a support agent for Acme.

                  Answer in English.
                usesBlocks: true
                blocks:
                  - blockId: d41a8f6b-9c27-4b13-a5e8-2f60c1d7b394
                    blockVersionId: 7e2b5a90-3c48-4d61-b9f7-05a8c2e14d6f
                    name: Brand voice
                    included: true
                    rendered: You are a support agent for Acme.
                    missingVariables: []
                  - blockId: 1f5c8b23-6d94-4e07-a2b8-9c31e5d70a46
                    blockVersionId: 8a04d7e2-1b63-4c95-8e27-5f9b0a6c3d18
                    name: Enterprise addendum
                    included: false
                    reason: display condition not met
                    rendered: ''
                    missingVariables: []
                droppedVariables: []
        '404':
          description: Not found
        '422':
          description: Prompt blocks could not be resolved
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Organization API key, generated in studio.sidenet.ai. Backend only —
        never in a browser.

````