HummingDeck Decks API

openapi: 3.2.0
info:
  title: HummingDeck Decks API
  version: 1.12.0
  description: 'The HummingDeck API. Provides document search, upload and replacement, room creation and structure (tabs, documents, links, embeds, sections), room archive and restore, document and room share link management, company/contact find-or-create operations, view and decision events, and webhooks for the Zapier integration.


    Two credential types are accepted, and they are not interchangeable:


    **Workspace API key** (`Authorization: Bearer hd_api_...`): issued by a workspace owner or admin in Workspace settings, Integrations, HummingDeck API. REST API access is available by request on Business and is enabled per workspace after review. A workspace can have multiple named keys, each with an explicit set of scopes and independent revocation. Each write scope includes the matching read scope; read scopes do not grant write access. The raw key is shown once at creation and is not retrievable afterwards; it expires one year after creation. Every key is bound permanently to its workspace, so a request cannot select or override its workspace. Webhook subscription endpoints are not available to this credential.


    **Zapier OAuth** (`Authorization: Bearer {access_token}`): issued through the OAuth authorization flow when a workspace connects the Zapier integration. Access tokens expire after 30 days; the 90-day refresh token obtains a new one. This is the only credential that can create or delete webhook subscriptions.


    Each operation documents its primary always-required workspace-key capability in `x-required-api-key-scope`. Additional always-required capabilities appear in `x-additional-required-api-key-scopes`; body-dependent capabilities appear in `x-conditional-api-key-scopes`, keyed by scope with the exact trigger as its value. `GET /me` requires no scope. A valid key that lacks a required capability receives `403 INSUFFICIENT_SCOPE`; the response names `requiredScope`.


    Manual keys and Zapier OAuth connections are limited per credential to 600 reads per 5 minutes, 120 writes per minute, 60 room-view reads per minute, and 20 uploads per hour. Shared workspace ceilings are twice those values across all credentials. Failed bearer authentication and invalid OAuth client authentication are each limited per trusted client IP to 60 attempts per 5 minutes. Requests may receive `429 RATE_LIMITED`; use the delta seconds in `Retry-After` before retrying. Rooms API JSON bodies are limited to 262,144 bytes; company, contact, share, and webhook JSON bodies are limited to 32,768 bytes; and document-upload and replacement multipart requests are limited to 32,505,856 bytes, including at most a 30 MiB file. Oversized bodies return `413 PAYLOAD_TOO_LARGE` before structured parsing.


    A request is rejected with 401 when the token is unknown or malformed, has expired, has been switched off, belongs to a workspace whose API access was turned off, or was issued by someone who is no longer an owner or admin of that workspace.'
  contact:
    name: HummingDeck Support
    url: https://hummingdeck.com
    email: support@hummingdeck.com
servers:
- url: https://app.hummingdeck.com/api/v1
  description: Production
security:
- apiToken: []
- oauth2: []
tags:
- name: Decks
paths:
  /decks:
    get:
      summary: Search documents
      description: Search documents by title within the authenticated team.
      operationId: searchDocuments
      x-required-api-key-scope: documents:read
      parameters:
      - name: title
        in: query
        required: true
        schema:
          type: string
        description: Title to search for (case-insensitive, partial match)
      responses:
        '200':
          description: Matching documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        '401':
          description: Not authenticated
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Decks
    post:
      summary: Upload a document
      description: Upload a new document to the team's library.
      operationId: uploadDocument
      x-required-api-key-scope: documents:write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Document file (PDF, PPTX, DOCX, HTML). Maximum 30 MB per API upload.
                title:
                  type: string
                  description: Document title
              required:
              - file
              - title
      responses:
        '200':
          description: Document uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedDocument'
        '400':
          description: Invalid file or missing title
        '401':
          description: Not authenticated
        '403':
          description: A required API-key scope is missing, or the plan limit is reached (PLAN_LIMIT_REACHED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Decks
  /decks/{deckId}/replace:
    post:
      summary: Replace a document file
      description: Replace an existing document in the authenticated workspace. Only a manually issued workspace API key with documents:write is accepted; Zapier OAuth credentials are rejected. Send only a local file in multipart/form-data. The new file must have the same file type as the current document, and the document must not have an active Proposal link. Existing document ID, title, delivery mode, Share Links, Room placements, access settings and analytics history are retained. Previewable replacements return processingStatus=pending while processing continues; check processingStatus before relying on the new preview. Download-only PDF and ZIP replacements return processingStatus=completed. Previewable HTML ZIP bundles require the workspace's ZIP-preview entitlement. The file limit is 30 MiB (31,457,280 bytes); the complete multipart request limit is 31 MiB (32,505,856 bytes). A repeated POST starts a new replacement. If the response is lost, inspect the current document or share view, or contact support before retrying.
      operationId: replaceDocument
      x-required-api-key-scope: documents:write
      security:
      - apiToken: []
      parameters:
      - name: deckId
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the document to replace
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: Local replacement file. Must have the same file type as the existing document and a matching filename extension (.pdf, .pptx, .docx, .xlsx, .xls, .html/.htm, or .zip); maximum 30 MiB.
              required:
              - file
              additionalProperties: false
      responses:
        '200':
          description: Replacement published. Previewable files continue processing; download-only files are completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadedDocument'
        '400':
          description: Invalid document ID or multipart body (VALIDATION_ERROR), unsupported file or missing/mismatched filename extension (INVALID_FORMAT), unreadable file (FILE_READ_ERROR), or replacement file type differs from the current file (TYPE_MISMATCH).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not authenticated
        '403':
          description: Zapier OAuth is not accepted (CREDENTIAL_NOT_ALLOWED), the API key lacks documents:write (INSUFFICIENT_SCOPE), or the workspace cannot replace a previewable HTML ZIP bundle (PLAN_LIMIT_REACHED).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Document does not exist, is deleted, or does not belong to the authenticated workspace (NOT_FOUND).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: An active Proposal link blocks replacement (PROPOSAL_LOCKED). A missing source, concurrent document change, or Proposal activated during publication returns REPLACEMENT_CONFLICT.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
      tags:
      - Decks
components:
  schemas:
    UploadedDocument:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the document
        title:
          type: string
          description: Document title
        fileType:
          type: string
          description: MIME type of the document
          example: application/pdf
        processingStatus:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          description: Previewable uploads and replacements can return pending while processing continues. A download-only replacement returns completed. Check status before relying on the preview.
        processingErrorCode:
          type:
          - string
          - 'null'
          description: Why processing failed, when processingStatus is failed.
      required:
      - id
      - title
      - fileType
      - processingStatus
      - processingErrorCode
      additionalProperties: false
    Document:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the document
        title:
          type: string
          description: Document title
        fileType:
          type: string
          description: MIME type of the document
          example: application/pdf
        deliveryMode:
          type: string
          enum:
          - preview
          - download_only
          description: download_only files are never previewed; recipients download them and open them on their device.
        pageCount:
          type:
          - integer
          - 'null'
          description: Number of pages when processing has determined it.
        thumbnailUrl:
          type:
          - string
          - 'null'
          format: uri
          description: Thumbnail image URL when one is available.
        processingStatus:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          description: Processing continues after upload. The document can go into a room right away; poll until completed before sending a link to it.
        processingErrorCode:
          type:
          - string
          - 'null'
          description: Why processing failed, when processingStatus is failed.
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the document was created.
      required:
      - id
      - title
      - fileType
      - deliveryMode
      - pageCount
      - thumbnailUrl
      - processingStatus
      - processingErrorCode
      - createdAt
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable code, present on some errors
          enum:
          - PLAN_LIMIT_REACHED
          - VALIDATION_ERROR
          - NOT_FOUND
          - ROOM_NOT_ACTIVE
          - ACCOUNT_CONFLICT
          - CREDENTIAL_NOT_ALLOWED
          - INSUFFICIENT_SCOPE
          - RATE_LIMITED
          - PAYLOAD_TOO_LARGE
          - INVALID_FORMAT
          - TYPE_MISMATCH
          - FILE_READ_ERROR
          - FILE_TOO_LARGE
          - FEATURE_NOT_AVAILABLE
          - PROPOSAL_LOCKED
          - REPLACEMENT_CONFLICT
          - TAB_TYPE_CONFLICT
          - LAST_TAB
          - TAB_NOT_EMPTY
          - TASK_BLOCKED
          - TASK_HIERARCHY_CYCLE
          - LEGACY_MAPPING_UNSUPPORTED
          - LABEL_NAME_CONFLICT
          - EMBED_PROVIDER_NOT_SUPPORTED
        kind:
          type: string
          enum:
          - room
          - docPerRoom
          - linksPerRoom
          - htmlBundle
          description: 'With PLAN_LIMIT_REACHED: the room limit or HTML bundle preview entitlement that blocked the request.'
        limit:
          type: integer
          description: 'With PLAN_LIMIT_REACHED on room endpoints: the plan''s limit.'
        feature:
          type: string
          enum:
          - restrictedAccess
          - emailCapture
          - linkExpiration
          - downloadControl
          - roomDiscussions
          description: 'With FEATURE_NOT_AVAILABLE: the plan feature the request needs.'
        requiredScope:
          type: string
          enum:
          - rooms:read
          - rooms:write
          - plan:read
          - plan:write
          - analytics:read
          - crm:read
          - crm:write
          - documents:read
          - documents:write
          description: 'With INSUFFICIENT_SCOPE: the capability the API key must be granted.'
      required:
      - error
  responses:
    InternalServerError:
      description: The request failed unexpectedly. The response is deliberately bounded and never includes internal error details.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                const: Internal server error
            required:
            - error
            additionalProperties: false
    PayloadTooLarge:
      description: Request body exceeds the byte ceiling documented for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InsufficientScope:
      description: The authenticated workspace API key lacks a scope required by this operation (INSUFFICIENT_SCOPE).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Rate limit exceeded. Retry after the number of seconds in Retry-After.
      headers:
        Retry-After:
          required: true
          schema:
            type: integer
            minimum: 1
          description: Seconds until the current fixed window resets.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiToken:
      type: http
      scheme: bearer
      bearerFormat: hd_api_...
      description: Named workspace API key issued by a workspace owner or admin. Prefixed hd_api_, shown once at creation, valid for one year, independently scoped and revoked, and bound permanently to its workspace. Each *:write scope includes the matching *:read capability. Not accepted on webhook subscription endpoints.
    oauth2:
      type: oauth2
      description: Issued by the Zapier integration's OAuth flow. Access tokens last 30 days; refresh tokens last 90 days. The only credential accepted on webhook subscription endpoints.
      flows:
        authorizationCode:
          authorizationUrl: https://app.hummingdeck.com/api/zapier/authorize
          tokenUrl: https://app.hummingdeck.com/api/zapier/token
          scopes: {}