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

# Apply a Playbook update preview

> Apply an approved, unexpired preview to staging.

Requires `playbook:write`.

The preview must have been created by the same API key. If staging changed
after the preview was created, Hobbes returns `409` without creating a version.
Create a new preview against the current `sectionsEtag`. Repeating a successful
apply returns the original result.


## OpenAPI

````yaml api-reference/openapi.json POST /api/v1/playbook/update-previews/{preview_id}/apply
openapi: 3.1.0
info:
  title: Hobbes API
  description: >

    Use the Hobbes API to read your organization's analyzed demo sessions,

    prospects, accounts, transcripts, and funnel metrics; create and manage

    personalized Custom Links; and, with explicit elevated scopes, inspect or
    update

    the structured Playbook and publish an exact staged agent version.


    **Authentication**: create an API key in Settings → API Keys, then send it

    as `Authorization: Bearer <key>` (or `x-api-key: <key>`). Keys are

    org-scoped; responses only ever contain your organization's data.


    **Scopes**: keys carry scopes (`sessions:read`, `people:read`,

    `accounts:read`, `analytics:read`, `transcripts:read`, `custom_links:read`,

    `custom_links:write`, `playbook:read`, `playbook:write`, `agent:publish`).

    `custom_links:write` also satisfies Custom Link read access. Raw transcript,

    Playbook, and publish access are separate opt-ins. Existing API keys do not

    receive new scopes automatically. Playbook writes are preview-first;
    production

    publishing requires the literal REST confirmation value documented by the

    endpoint and runs asynchronously through Hobbes' conversation-test gate.


    **Rate limits**: keys allow 120 requests per minute by default. Responses

    include `X-RateLimit-Limit` and `X-RateLimit-Remaining`; 429 responses
    include

    `Retry-After`. Transcript access has a separate quota of 2,000 reads per

    organization per UTC day. Custom Link mutations are limited to 10 requests
    per

    minute per organization. Creation and thumbnail rendering also use weighted

    hourly and daily organization quotas, so one request containing 500 links is

    one HTTP request but consumes up to 500 creation and 500 render units.


    **Support**: every response carries an `X-Request-ID` header. Include it
    when

    reporting an issue so we can find the exact request in our logs.


    **Stability**: changes within v1 are additive only. Fields may be added to

    responses; existing fields are never removed or renamed.
  version: 1.0.0
servers:
  - url: https://api-us.hihobbes.com
    description: Production
security:
  - bearer: []
  - apiKeyHeader: []
tags:
  - name: Sessions
    description: Analyzed demo sessions and their transcripts.
  - name: People
    description: Prospect profiles aggregated across sessions.
  - name: Accounts
    description: Company-level engagement rollups by email domain.
  - name: Metrics
    description: Aggregate funnel performance over a trailing window.
  - name: Custom Links
    description: Create and manage personalized links.
  - name: Custom Link Jobs
    description: Poll, cancel, and retry asynchronous Custom Link work.
  - name: Custom Link Campaigns
    description: Organize Custom Links into campaigns.
  - name: Playbook
    description: Inspect, preview, and apply structured Playbook changes.
  - name: Agent Publishing
    description: Publish an exact staged agent version asynchronously.
paths:
  /api/v1/playbook/update-previews/{preview_id}/apply:
    post:
      tags:
        - Playbook
      summary: Apply a Playbook update preview
      description: >-
        Apply an unexpired preview created by the same API key to staging.
        Staging drift fails without creating a version; repeated applies return
        the original result.
      operationId: v1_apply_playbook_update
      parameters:
        - name: preview_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: Preview Id
            description: Playbook update preview UUID.
          description: Playbook update preview UUID.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplyPlaybookUpdateResponse'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
        '401':
          description: API key required or invalid.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key required or invalid.
        '403':
          description: API key does not include the required scope.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key does not include the required scope.
        '404':
          description: Preview not found for this organization and API key.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Preview not found for this organization and API key.
        '409':
          description: The operation conflicts with current state or idempotency history.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: >-
                      The operation conflicts with current state or idempotency
                      history.
        '410':
          description: The saved preview has expired and must be recreated.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: The saved preview has expired and must be recreated.
        '422':
          description: A path, query, header, or request field failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
        '429':
          description: Rate limit or organization quota exceeded.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
            X-RateLimit-Reset:
              description: Unix timestamp when the limiting window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Rate limit or organization quota exceeded.
        '503':
          description: The workflow is disabled or temporarily unavailable.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
            X-RateLimit-Reset:
              description: Unix timestamp when the limiting window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: The workflow is disabled or temporarily unavailable.
components:
  schemas:
    ApplyPlaybookUpdateResponse:
      properties:
        previewId:
          type: string
          format: uuid
          title: Previewid
        version:
          type: integer
          title: Version
        sectionsEtag:
          type: string
          title: Sectionsetag
        productionVersion:
          type: integer
          title: Productionversion
        stagingVersion:
          type: integer
          title: Stagingversion
        noChange:
          type: boolean
          title: Nochange
          default: false
        links:
          $ref: '#/components/schemas/AgentLinks'
        changes:
          items:
            $ref: '#/components/schemas/ChangedSection'
          type: array
          title: Changes
      type: object
      required:
        - previewId
        - version
        - sectionsEtag
        - productionVersion
        - stagingVersion
        - links
        - changes
      title: ApplyPlaybookUpdateResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentLinks:
      properties:
        staging:
          $ref: '#/components/schemas/AgentLink'
        production:
          $ref: '#/components/schemas/AgentLink'
      type: object
      required:
        - staging
        - production
      title: AgentLinks
    ChangedSection:
      properties:
        sectionKey:
          type: string
          title: Sectionkey
        title:
          type: string
          title: Title
        action:
          type: string
          enum:
            - added
            - updated
            - removed
          title: Action
        before:
          title: Before
        after:
          title: After
      type: object
      required:
        - sectionKey
        - title
        - action
      title: ChangedSection
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    AgentLink:
      properties:
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        availabilityReason:
          anyOf:
            - type: string
            - type: 'null'
          title: Availabilityreason
      type: object
      title: AgentLink
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Hobbes API key with the `hb_live_` prefix.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative to the Bearer authorization header.

````