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

# JobHandy Public API reference

> Authoritative reference for JobHandy operations, request behavior, resources, errors, and the OpenAPI 3.1 contract.

<Badge color="green" shape="pill" icon="circle-check">Production</Badge> <Badge color="purple" shape="pill" icon="file-code">OpenAPI 3.1</Badge>

## Connection details

| Setting            | Value                            |
| ------------------ | -------------------------------- |
| Base URL           | `https://api.jobhandy.io/v1`     |
| Authentication     | `X-API-Key` except `GET /health` |
| Tenant selection   | `X-Tenant-ID` where documented   |
| Correlation        | `X-Request-ID`, UUID v4 or v7    |
| JSON media type    | `application/json`               |
| Public environment | Production only                  |

## Resources

<Columns cols={3}>
  <Card title="Employees" icon="users" href="/api-reference/employees">
    Master data, account blocking, tenant placement, and division assignment.
  </Card>

  <Card title="Orders" icon="shopping-bag" href="/api-reference/orders">
    Retrieval, HR approval decisions, products, contract data, and documents.
  </Card>

  <Card title="Incidents" icon="triangle-alert" href="/api-reference/incidents">
    Reporting, server-managed lifecycle state, supported updates, and evidence files.
  </Card>

  <Card title="Divisions" icon="network" href="/api-reference/divisions">
    Tenant-owned hierarchy, sibling order, parent relationships, and cost centers.
  </Card>

  <Card title="Payroll exports" icon="file-spreadsheet" href="/api-reference/payroll-export-documents">
    Read-only document metadata and available file downloads.
  </Card>

  <Card title="Health" icon="heart-pulse" href="/api-reference/health">
    Public basic availability endpoint.
  </Card>
</Columns>

## Operation matrix

| Resource                 | Read | Create |           Update | Delete | Special operation                                    |
| ------------------------ | ---: | -----: | ---------------: | -----: | ---------------------------------------------------- |
| Employees                |  Yes |    Yes |              Yes |     No | Block/unblock through update                         |
| Orders                   |  Yes |     No |    Decision only |     No | Approve or reject under review; download attachments |
| Incidents                |  Yes |    Yes | Supported fields |     No | Upload permitted attachments                         |
| Divisions                |  Yes |    Yes |              Yes |     No | Hierarchy validation                                 |
| Payroll export documents |  Yes |     No |               No |     No | Download available file                              |
| Health                   |  Yes |     No |               No |     No | No authentication                                    |

## Common behavior

<AccordionGroup>
  <Accordion title="Authentication and scope" defaultOpen>
    Protected requests require `X-API-Key`. The API enforces the key's tenant and division scope on every resource and reference.
  </Accordion>

  <Accordion title="Optional parameters">
    Optional query and header parameters are visible in the reference but are omitted from generated requests until selected.
  </Accordion>

  <Accordion title="Dry runs">
    Supported writes accept `dryRun=true` and return the documented projection without applying persistence or side effects.
  </Accordion>

  <Accordion title="Errors">
    Errors use `{ "error": { "code", "message", "requestId" } }`. The response list on each operation is authoritative.
  </Accordion>

  <Accordion title="Retries">
    Reads can be retried under bounded policies. Writes require current-state reconciliation after timeouts or conflicts.
  </Accordion>
</AccordionGroup>

## Before using an operation

1. Confirm the API key contains the required scope.
2. Determine whether `X-Tenant-ID` is needed.
3. Review side effects and dry-run support.
4. Generate and log `X-Request-ID`.
5. Handle every documented response status.
6. Define reconciliation before retrying a write.

<CardGroup cols={2}>
  <Card title="Error handling" icon="circle-alert" href="/concepts/error-handling">
    Map HTTP status, API error code, corrective action, and retryability.
  </Card>

  <Card title="OpenAPI specification" icon="download" href="/api-reference/openapi-specification">
    Download the complete machine-readable contract.
  </Card>
</CardGroup>