> ## 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.

# OpenAPI specification

> Download the authoritative JobHandy Public API contract in OpenAPI 3.1 JSON or YAML format.

<Badge color="purple" shape="pill" icon="braces">OpenAPI 3.1.0</Badge> <Badge color="green" shape="pill" icon="circle-check">Production contract</Badge>

Both files describe the same public API and use the production server `https://api.jobhandy.io/v1`.

<Columns cols={2}>
  <Card title="Download JSON" icon="braces" href="https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.json" arrow="true">
    Machine-readable OpenAPI 3.1 contract in JSON format.
  </Card>

  <Card title="Download YAML" icon="file-code" href="https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.yaml" arrow="true">
    Semantically equivalent OpenAPI 3.1 contract in YAML format.
  </Card>
</Columns>

## Contract profile

| Property          | Value                        |
| ----------------- | ---------------------------- |
| OpenAPI version   | `3.1.0`                      |
| API version       | `1.0.0`                      |
| Production server | `https://api.jobhandy.io/v1` |
| Paths             | `15`                         |
| Operations        | `21`                         |
| Component schemas | `25`                         |
| Authentication    | API key in `X-API-Key`       |

<Warning>
  The current version `1.0.0` includes updated `Order`, `OrderHrHistory`, `OrderProduct`, and division-order schemas. Review the [changelog](/operations/changelog) and update affected client models before adopting the refreshed specification.
</Warning>

## Recommended use

* generate typed clients and models
* import endpoints into API testing tools
* validate requests and responses in CI
* compare contract releases before client adoption
* build contract tests and mocks
* archive the exact adopted specification with each client release

## Adoption workflow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Download specification] --> B[Validate and checksum]
    B --> C[Diff against adopted version]
    C --> D[Generate or update client]
    D --> E[Run contract tests]
    E --> F[Run customer acceptance tests]
    F --> G[Record adopted version]
```

<Card title="Tooling and client generation" icon="wrench" horizontal href="/operations/tooling-openapi">
  Import the contract, generate clients, and automate compatibility checks.
</Card>