HummingDeck Shares API

openapi: 3.2.0
info:
  title: HummingDeck Shares 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: Shares
paths:
  /shares:
    post:
      summary: Create a share link
      description: 'Generate a tracked share link. The returned URL uses the workspace''s active custom domain when the workspace is entitled to use custom domains; otherwise it uses the HummingDeck domain. For personal links, HummingDeck resolves the contact by its email and the company by its name, creating records that are missing. The response reports which account records were created. Explicit anonymous links never create account records.


        Workspace API keys always need `documents:write`. A personal link also needs `crm:write` when the request supplies recipient, contact, or company fields that HummingDeck resolves against CRM records.'
      operationId: createShare
      x-required-api-key-scope: documents:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                deckId:
                  type: string
                  description: ID of the document to share
                recipientName:
                  type: string
                  description: Name of the recipient (optional)
                recipientEmail:
                  type: string
                  format: email
                  description: Email of the recipient (optional)
                contactId:
                  type: string
                  format: uuid
                  description: Existing contact in the authenticated workspace. When recipientEmail is also supplied, it must identify this contact.
                companyId:
                  type: string
                  format: uuid
                  description: Existing company in the authenticated workspace. Mutually exclusive with companyName.
                companyName:
                  type: string
                  maxLength: 255
                  description: Company to find case-insensitively or create. Mutually exclusive with companyId.
                companyDomain:
                  type: string
                  maxLength: 255
                  description: Domain used when companyName creates or enriches a company. Requires companyName.
                type:
                  type: string
                  enum:
                  - personal
                  - anonymous
                  description: Link type. Defaults to personal when any recipient/contact/company field is present, otherwise anonymous. Explicit anonymous links do not create account records.
              required:
              - deckId
      responses:
        '200':
          description: Share link created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ShareLink'
        '400':
          description: Invalid request
        '401':
          description: Not authenticated
        '403':
          description: A required API-key scope is missing, or the standalone document-link plan limit is reached (PLAN_LIMIT_REACHED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 'Not found: the document, contact, or company does not exist in the authenticated workspace'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'Conflict: supplied contact/email/company identifiers disagree with existing account data'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-conditional-api-key-scopes:
        crm:write: Required for a non-anonymous share when the request supplies contactId, companyId, companyName, recipientEmail, or recipientName.
      tags:
      - Shares
components:
  schemas:
    Company:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the company
        name:
          type: string
        domain:
          type:
          - string
          - 'null'
        logoUrl:
          type:
          - string
          - 'null'
          format: uri
        industry:
          type:
          - string
          - 'null'
        size:
          type:
          - string
          - 'null'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - domain
      - logoUrl
      - industry
      - size
      - createdAt
      - updatedAt
    ShareLink:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the share link
        slug:
          type: string
          description: URL slug for the share link
        type:
          type: string
          enum:
          - personal
          - anonymous
          description: Link type
        recipientName:
          type:
          - string
          - 'null'
          description: Recipient name, for personal links
        recipientEmail:
          type:
          - string
          - 'null'
          description: Recipient email, for personal links
        contact:
          oneOf:
          - $ref: '#/components/schemas/Contact'
          - type: 'null'
          description: Contact attached to the link, when personal account resolution was requested
        contactCreated:
          type: boolean
          description: True when this request created the returned contact
        company:
          oneOf:
          - $ref: '#/components/schemas/Company'
          - type: 'null'
          description: Company attached to the link, when resolved
        companyCreated:
          type: boolean
          description: True when this request created the returned company
        shareUrl:
          type: string
          format: uri
          description: Full trackable URL to view the shared document, using the workspace's eligible active custom domain when configured
          example: https://hummingdeck.com/view/kry377wf7gb7i2pt
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - slug
      - type
      - contactCreated
      - companyCreated
      - shareUrl
      - createdAt
    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
    Contact:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the contact
        firstName:
          type: string
        lastName:
          type: string
        email:
          type:
          - string
          - 'null'
          format: email
        title:
          type:
          - string
          - 'null'
          description: Job title
        leadId:
          type:
          - string
          - 'null'
          description: Deprecated alias for companyId
          deprecated: true
        leadName:
          type:
          - string
          - 'null'
          description: Deprecated alias for companyName
          deprecated: true
        companyId:
          type:
          - string
          - 'null'
          description: Associated company ID, null when the contact has no company in this workspace
        companyName:
          type:
          - string
          - 'null'
          description: Associated company name
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - firstName
      - lastName
      - email
      - companyId
      - companyName
  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'
    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: {}