HollyHR Documents API

openapi: 3.2.0
info:
  title: HollyHR API Reference Documents API
  version: 1.0.0-foundation
  description: Governed Public Preview API with organisation-scoped reads and bounded signed-webhook management available on every plan, and governed programmatic writes included on Standard and above through explicitly selected scopes. This version covers API-key context, people directory sync, safe people setup, conditional setup-field updates, safe lifecycle actions, safe employment writes, canonical org-unit reads and person org links, working-pattern reads and writes, safe time-off writes, time-off sync, public holidays, document metadata sync, reference data, and outbound webhook management. Responses use explicit deny-by-default projections and opaque public ids; person ids are stored random tenant-person identifiers while other resource ids remain encrypted. orgId is always resolved from the bearer key and is never accepted from request input.
servers:
- url: /api/v1
  description: Public API path on the current HollyHR app origin.
- url: https://sandbox.hollyhr.com/api/v1
  description: Seeded HollyHR sandbox tenant for hhr_test_ API keys.
security:
- ApiKeyAuth: []
tags:
- name: Documents
  description: Read-only document metadata; file bytes are not exposed.
paths:
  /documents:
    get:
      operationId: listDocuments
      tags:
      - Documents
      summary: List document metadata
      description: Lists document metadata only. Storage keys, signed URLs, file bytes, and document contents are not returned. The optional person_id filter must be an opaque public person id for the same tenant.
      security:
      - ApiKeyAuth: []
      x-required-scope: documents:read
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
        required: false
        name: limit
        in: query
      - schema:
          type: string
          minLength: 1
        required: false
        name: cursor
        in: query
      - schema:
          type: string
          pattern: ^[0123456789abcdefghjkmnpqrstvwxyz]{12}$
        required: false
        name: person_id
        in: query
      - schema:
          type: string
          format: date-time
        required: false
        name: updated_since
        in: query
      responses:
        '200':
          description: A cursor page of document metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentPage'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, unknown, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Missing scope or plan entitlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Responses include Retry-After and rate-limit metadata where available.
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying the request.
            RateLimit-Limit:
              schema:
                type: string
              description: Current route bucket limit.
            RateLimit-Remaining:
              schema:
                type: string
              description: Requests remaining in the current route bucket window.
            RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current route bucket resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-hollyhr-domain-capabilities:
      - documents.metadata.view
      - documents.organisation.manage
  /documents/{documentId}:
    get:
      operationId: getDocument
      tags:
      - Documents
      summary: Fetch one document metadata record
      description: Fetches document metadata only. Storage keys, signed URLs, file bytes, and document contents are not returned.
      security:
      - ApiKeyAuth: []
      x-required-scope: documents:read
      parameters:
      - schema:
          type: string
          pattern: ^doc_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
          description: Encrypted public document id.
        required: true
        description: Encrypted public document id.
        name: documentId
        in: path
      responses:
        '200':
          description: A document metadata projection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, unknown, revoked, or expired API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Missing scope or plan entitlement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Document not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited. Responses include Retry-After and rate-limit metadata where available.
          headers:
            Retry-After:
              schema:
                type: string
              description: Seconds to wait before retrying the request.
            RateLimit-Limit:
              schema:
                type: string
              description: Current route bucket limit.
            RateLimit-Remaining:
              schema:
                type: string
              description: Requests remaining in the current route bucket window.
            RateLimit-Reset:
              schema:
                type: string
              description: Seconds until the current route bucket resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      x-hollyhr-domain-capabilities:
      - documents.content.view
components:
  schemas:
    DocumentPage:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                pattern: ^doc_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
              name:
                type: string
              person_id:
                type: string
                pattern: ^[0123456789abcdefghjkmnpqrstvwxyz]{12}$
              category:
                type:
                - string
                - 'null'
              content_type:
                type:
                - string
                - 'null'
              size_bytes:
                type:
                - integer
                - 'null'
              created_at:
                type: string
                format: date-time
              updated_at:
                type: string
                format: date-time
            required:
            - id
            - name
            - person_id
            - category
            - content_type
            - size_bytes
            - created_at
            - updated_at
            additionalProperties: false
        pagination:
          type: object
          properties:
            next_cursor:
              type:
              - string
              - 'null'
            has_more:
              type: boolean
            limit:
              type: integer
              minimum: 1
              maximum: 100
          required:
          - next_cursor
          - has_more
          - limit
          additionalProperties: false
      required:
      - data
      - pagination
      additionalProperties: false
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
              - invalid_request
              - authentication_required
              - permission_denied
              - not_found
              - rate_limited
              - idempotency_required
              - idempotency_conflict
              - conflict
              - precondition_required
              - precondition_failed
              - internal_error
            message:
              type: string
            request_id:
              type: string
              pattern: ^[a-zA-Z0-9._:-]{8,64}$
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  issue:
                    type: string
                required:
                - field
                - issue
                additionalProperties: false
          required:
          - code
          - message
          - request_id
          additionalProperties: false
      required:
      - error
      additionalProperties: false
    DocumentResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              pattern: ^doc_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
            name:
              type: string
            person_id:
              type: string
              pattern: ^[0123456789abcdefghjkmnpqrstvwxyz]{12}$
            category:
              type:
              - string
              - 'null'
            content_type:
              type:
              - string
              - 'null'
            size_bytes:
              type:
              - integer
              - 'null'
            created_at:
              type: string
              format: date-time
            updated_at:
              type: string
              format: date-time
          required:
          - id
          - name
          - person_id
          - category
          - content_type
          - size_bytes
          - created_at
          - updated_at
          additionalProperties: false
      required:
      - data
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: HollyHR API-key bearer token. Each credential is attached to one stable organisation-bound programmatic principal, so rotation does not change the actor or its audit identity. Effective access remains the intersection of the key scopes, current principal grant, plan entitlement and runtime controls.
x-provenance:
  method: harvested
  publisher: HollyHR
  source: https://developers.hollyhr.com/openapi.v1.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)