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

# Service health check

> Returns the health status of the service and its dependencies.

**status** values:
- `ok` — all systems operational
- `degraded` — service running but some DSL files failed to load
- `unhealthy` — critical failure (should never return this; service would be down)

Monitor the `registry.load_errors` field to detect DSL configuration issues.



## OpenAPI

````yaml /openapi.json get /health
openapi: 3.1.0
info:
  title: Payroll API
  description: >

    ## Payroll Infrastructure API for Latin America


    **Stripe for payroll** — embedded payroll calculation infrastructure.


    ### Overview


    This API performs payroll calculations for Mexico, Colombia, Brazil,
    Argentina,

    and Chile. It is a **pure computation engine**: give it employee data, get
    back

    a fully itemized payroll breakdown.


    ### Key concepts


    - **Scheme** — A country-specific payroll ruleset (e.g., Mexico `ordinario`,
    Colombia `integral`).
      Use `GET /v1/payroll/schemes/{country}` to discover available schemes.
    - **Calculation** — A single employee payroll run for one period.

    - **Audit trail** — A step-by-step trace of every formula evaluated.
    Required for
      legal compliance in most Latin American countries.

    ### Decimal precision


    All monetary amounts are returned as **JSON strings** (not numbers) to
    prevent

    floating-point precision loss in client languages. Parse them with your
    language's

    `Decimal` type before doing any arithmetic.


    ```

    ✅ correct:  {"net_salary": "20039.25"}

    ❌ wrong:    {"net_salary": 20039.25}  // could lose precision

    ```


    ### Authentication


    All endpoints require a Bearer API key:

    ```

    Authorization: Bearer your_api_key_here

    ```


    ### Error format


    All errors follow a consistent structure:

    ```json

    {
      "error": {
        "code": "SCHEME_NOT_FOUND",
        "message": "Human-readable description",
        "details": {},
        "request_id": "abc123"
      }
    }

    ```


    Use the `code` field (not the HTTP status) for programmatic error handling.

    The `request_id` links to server logs — include it when contacting support.


    ### Payouts (mock provider)


    The `/v1/payouts` surface lets you pay an employee their `net_salary` after
    a

    calculation. In v1 every payout is handled by an **in-process mock
    provider** —

    no real funds are moved. Every response is marked with `mock: true` in the
    body

    and `X-Clevis-Mock: true` as a response header.


    - Magic `external_id` prefixes (`MOCK_REJECT_INTAKE_`, `MOCK_REJECT_BANK_`,
      `MOCK_SLOW_`, `MOCK_STUCK_`, `MOCK_OK_`) trigger deterministic outcomes for
      demos and tests.
    - `processing.step_seconds: 0` makes the payout transition to its terminal
      status synchronously before the response is returned.
    - Idempotency is supported via the `Idempotency-Key` header or via the
      `external_id` field (per API key).

    See `docs/specs/04_payout_mock_endpoint.md` for the full contract. The real

    dLocal integration will be a config flip behind the same interface; this

    client-facing contract does not change.
  contact:
    name: Payroll API Support
    email: api@payroll.io
  license:
    name: Proprietary
  version: 1.0.0
servers: []
security: []
tags:
  - name: Payroll
    description: Payroll calculation endpoints. All monetary values are JSON strings.
  - name: Payouts
    description: >-
      Single-beneficiary payout endpoints backed by an in-process **mock**
      provider in v1 — no real funds are moved. Every response carries `mock:
      true` and the `X-Clevis-Mock: true` header. Magic trigger values (e.g.
      `external_id` prefixed with `MOCK_REJECT_BANK_`) force deterministic
      outcomes for demos and tests.
  - name: Schemes & Health
    description: Discover available payroll schemes and check service health.
  - name: Health
    description: Service health and readiness checks.
paths:
  /health:
    get:
      tags:
        - Schemes & Health
        - Health
      summary: Service health check
      description: >-
        Returns the health status of the service and its dependencies.


        **status** values:

        - `ok` — all systems operational

        - `degraded` — service running but some DSL files failed to load

        - `unhealthy` — critical failure (should never return this; service
        would be down)


        Monitor the `registry.load_errors` field to detect DSL configuration
        issues.
      operationId: Schemes & Health_health
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
components:
  schemas:
    HealthResponse:
      properties:
        status:
          type: string
          enum:
            - ok
            - degraded
            - unhealthy
          title: Status
        version:
          type: string
          title: Version
        environment:
          type: string
          title: Environment
        registry:
          additionalProperties: true
          type: object
          title: Registry
          description: 'DSL registry status: how many schemes are loaded, any load errors.'
        payouts:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Payouts
          description: >-
            Payout subsystem status. Present when PAYOUTS_ENABLED=true. Shape:
            {enabled, provider, mode, open_payouts}.
        uptime_seconds:
          type: number
          title: Uptime Seconds
      type: object
      required:
        - status
        - version
        - environment
        - registry
        - uptime_seconds
      title: HealthResponse
      description: Service health status.

````