HollyHR Meta API

openapi: 3.2.0
info:
  title: HollyHR API Reference Meta 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: Meta
  description: API-key context.
paths:
  /me:
    get:
      operationId: getApiPrincipal
      tags:
      - Meta
      summary: Inspect the authenticated API key context
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Authenticated API key context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeResponse'
        '401':
          description: Missing, malformed, unknown, revoked, or expired API key.
          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:
      - settings.api.manage
  /metadata:
    get:
      operationId: getApiMetadata
      tags:
      - Meta
      summary: Inspect the public API metadata catalogue
      description: Returns a generated machine-readable catalogue of routes, required scopes, query/path parameters, schema fields, scope field categories, and webhook event scope requirements. The catalogue is generated from the same OpenAPI/Zod contract source as the reference docs.
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Public API metadata catalogue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataResponse'
        '401':
          description: Missing, malformed, unknown, revoked, or expired API key.
          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:
      - settings.api.manage
components:
  schemas:
    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
    MetadataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            metadata_version:
              type: string
              enum:
              - v1
            api_version:
              type: string
            generated_from:
              type: string
            routes:
              type: array
              items:
                type: object
                properties:
                  method:
                    type: string
                  path:
                    type: string
                  operation_id:
                    type: string
                  domain_capability_ids:
                    type: array
                    items:
                      type: string
                      enum:
                      - documents.content.view
                      - documents.metadata.view
                      - documents.organisation.manage
                      - integrations.provider-mappings.view
                      - organisation.employers.manage
                      - organisation.employers.view
                      - organisation.units.manage
                      - organisation.units.view
                      - payroll.changes.export
                      - payroll.readiness.export
                      - people.avatar.view
                      - people.create
                      - people.custom-fields.update
                      - people.custom-fields.view
                      - people.directory.view
                      - people.employment-history.create
                      - people.employment-history.update
                      - people.employment-history.view
                      - people.employment.update
                      - people.employment.view
                      - people.lifecycle.end
                      - people.lifecycle.reactivate
                      - people.org-links.view
                      - people.personal-profile.view
                      - people.profile.update
                      - people.profile.view
                      - reference-data.view
                      - settings.api.manage
                      - settings.custom-fields.manage
                      - settings.integrations.view
                      - settings.organisation.manage
                      - settings.time-off-categories.manage
                      - settings.time-off.manage
                      - settings.working-patterns.manage
                      - settings.workplace.manage
                      - time-off.balance-ledger.view
                      - time-off.balance.adjust
                      - time-off.balance.view
                      - time-off.organisation-calendar.view
                      - time-off.public-holidays.view
                      - time-off.record.cancel
                      - time-off.record.update
                      - time-off.records.view
                      - time-off.request.approve
                      - time-off.request.create
                      - time-off.request.decline
                      - webhooks.manage
                      - working-patterns.manage
                      - working-patterns.view
                    minItems: 1
                  summary:
                    type: string
                  tags:
                    type: array
                    items:
                      type: string
                  required_scope:
                    type:
                    - string
                    - 'null'
                    enum:
                    - organisation:read
                    - people:read
                    - people:personal:read
                    - people:avatar:read
                    - people:write
                    - custom_fields:read
                    - custom_fields:write
                    - reference:read
                    - org_units:read
                    - org_units:write
                    - employers:read
                    - employers:write
                    - working_patterns:read
                    - working_patterns:write
                    - time_off:read
                    - time_off:write
                    - time_off:balance:write
                    - time_off:config:write
                    - documents:read
                    - provider_mappings:read
                    - payroll_exports:read
                    - webhooks:manage
                    - mcp:write
                    - null
                  path_parameters:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        required:
                          type: boolean
                        type:
                          type: string
                        enum_values:
                          type: array
                          items:
                            type: string
                      required:
                      - name
                      - required
                      - type
                      - enum_values
                      additionalProperties: false
                  query_parameters:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        required:
                          type: boolean
                        type:
                          type: string
                        enum_values:
                          type: array
                          items:
                            type: string
                      required:
                      - name
                      - required
                      - type
                      - enum_values
                      additionalProperties: false
                  response_statuses:
                    type: array
                    items:
                      type: string
                required:
                - method
                - path
                - operation_id
                - domain_capability_ids
                - summary
                - tags
                - required_scope
                - path_parameters
                - query_parameters
                - response_statuses
                additionalProperties: false
            schemas:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  fields:
                    type: array
                    items:
                      type: object
                      properties:
                        path:
                          type: string
                        type:
                          type: string
                        required:
                          type: boolean
                        enum_values:
                          type: array
                          items:
                            type: string
                      required:
                      - path
                      - type
                      - required
                      - enum_values
                      additionalProperties: false
                required:
                - name
                - fields
                additionalProperties: false
            scopes:
              type: array
              items:
                type: object
                properties:
                  scope:
                    type: string
                    enum:
                    - organisation:read
                    - people:read
                    - people:personal:read
                    - people:avatar:read
                    - people:write
                    - custom_fields:read
                    - custom_fields:write
                    - reference:read
                    - org_units:read
                    - org_units:write
                    - employers:read
                    - employers:write
                    - working_patterns:read
                    - working_patterns:write
                    - time_off:read
                    - time_off:write
                    - time_off:balance:write
                    - time_off:config:write
                    - documents:read
                    - provider_mappings:read
                    - payroll_exports:read
                    - webhooks:manage
                    - mcp:write
                  field_categories:
                    type: array
                    items:
                      type: string
                required:
                - scope
                - field_categories
                additionalProperties: false
            field_categories:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  label:
                    type: string
                  sensitivity:
                    type: string
                    enum:
                    - standard
                    - standard_hr
                    - elevated
                required:
                - id
                - label
                - sensitivity
                additionalProperties: false
            webhook_events:
              type: array
              items:
                type: object
                properties:
                  event_type:
                    type: string
                    enum:
                    - person.created
                    - person.updated
                    - person.ended
                    - person.reactivated
                    - time_off.created
                    - time_off.updated
                    - time_off.approved
                    - time_off.declined
                    - time_off.cancelled
                    - time_off_category.created
                    - time_off_category.updated
                    - time_off_category.archived
                    - time_off_settings.updated
                    - org_unit.created
                    - org_unit.updated
                    - org_unit.archived
                    - org_unit.reactivated
                    - working_pattern.created
                    - working_pattern.updated
                    - working_pattern.archived
                    - webhook.test
                  required_scopes:
                    type: array
                    items:
                      type: string
                      enum:
                      - organisation:read
                      - people:read
                      - people:personal:read
                      - people:avatar:read
                      - people:write
                      - custom_fields:read
                      - custom_fields:write
                      - reference:read
                      - org_units:read
                      - org_units:write
                      - employers:read
                      - employers:write
                      - working_patterns:read
                      - working_patterns:write
                      - time_off:read
                      - time_off:write
                      - time_off:balance:write
                      - time_off:config:write
                      - documents:read
                      - provider_mappings:read
                      - payroll_exports:read
                      - webhooks:manage
                      - mcp:write
                required:
                - event_type
                - required_scopes
                additionalProperties: false
          required:
          - metadata_version
          - api_version
          - generated_from
          - routes
          - schemas
          - scopes
          - field_categories
          - webhook_events
          additionalProperties: false
      required:
      - data
      additionalProperties: false
    MeResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            organisation:
              type: object
              properties:
                id:
                  type: string
                  pattern: ^org_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
              required:
              - id
              additionalProperties: false
            api_key:
              type: object
              properties:
                key_id:
                  type: string
                scopes:
                  type: array
                  items:
                    type: string
                    enum:
                    - organisation:read
                    - people:read
                    - people:personal:read
                    - people:avatar:read
                    - people:write
                    - custom_fields:read
                    - custom_fields:write
                    - reference:read
                    - org_units:read
                    - org_units:write
                    - employers:read
                    - employers:write
                    - working_patterns:read
                    - working_patterns:write
                    - time_off:read
                    - time_off:write
                    - time_off:balance:write
                    - time_off:config:write
                    - documents:read
                    - provider_mappings:read
                    - payroll_exports:read
                    - webhooks:manage
                    - mcp:write
              required:
              - key_id
              - scopes
              additionalProperties: false
            environment:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - live
                  - sandbox
                  description: API-key environment. Live keys report live; hhr_test_ keys report sandbox.
                sandbox:
                  type: boolean
                  description: True only when type is sandbox; false when type is live.
              required:
              - type
              - sandbox
              additionalProperties: false
            actor:
              type: object
              properties:
                type:
                  type: string
                  enum:
                  - api_key
                key_id:
                  type: string
              required:
              - type
              - key_id
              additionalProperties: false
          required:
          - organisation
          - api_key
          - environment
          - actor
          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)