> ## Documentation Index
> Fetch the complete documentation index at: https://humanity-eaeda8f6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Everything in the reference tab is powered by the generated OpenAPI.

This reference is sourced from the same OpenAPI document that ships with the SDK and drives Humanity’s public playground. Download it to plug into Postman, Stoplight, or your preferred client.

<Card title="Download the spec" icon="file" href="https://github.com/humanity-org/hp-dev-api-docs/blob/main/docs/api-reference/openapi.json">
  Same document Mintlify uses to render the interactive playground. You can also request a signed copy from DevRel if you need to pin to a specific version.
</Card>

## Base URLs & auth

| Environment | Base URL                               |
| ----------- | -------------------------------------- |
| Sandbox     | `https://api.sandbox.humanity.org/v2/` |
| Production  | `https://api.humanity.org/v2/`         |

All endpoints require HTTPS and bearer tokens. Public clients must follow OAuth 2.1 + PKCE (`code_challenge_method=S256`). Service-to-service flows can use confidential client credentials where approved.

## Resources at a glance

| Category       | Endpoints                                                                                      | Purpose                                             |
| -------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| OAuth          | `/oauth/authorize`, `/oauth/token`, `/oauth/revoke`, `/oauth/authorize/*`                      | Issue, exchange, approve/deny, and revoke tokens.   |
| Presets        | `/presets/{preset_name}`, `/presets/batch`, `/consent/presets`                                 | Verify Humanity presets individually or in bulk.    |
| Status feeds   | `/credentials`, `/authorizations`                                                              | Poll for credential or authorization changes.       |
| Access control | `/access/requests/standard`, `/access/developer/accept`, `/access/me`                          | Manage developer onboarding and keys.               |
| Discovery      | `/.well-known/hp-configuration`, `/.well-known/openid-configuration`, `/.well-known/jwks.json` | Fetch metadata, OAuth URLs, and JWKS sets.          |
| Health         | `/health`, `/ready`                                                                            | Operational probes for load balancers and monitors. |

Each page under **OAuth & Consent**, **Feeds & Access**, and **Discovery & Health** maps directly to an OpenAPI operation. Set the server dropdown (sandbox or production) and hit **Try it** to execute real requests with your bearer token.

## Working with the spec

1. Download the JSON file above or fetch it programmatically from `https://docs.humanity.app/api-reference/openapi.json`.
2. Import it into your API tooling. Popular options:
   * Postman/Insomnia for manual testing
   * Stoplight Studio or VS Code OpenAPI viewers for schema exploration
   * `openapi-generator` / `orval` if you need a client in another language
3. Keep an eye on the `version` field—Humanity increments it whenever contracts change. DevRel announcements include release notes and deprecation windows.

## Authentication reminders

All operations require HTTPS and a valid access token. If you call the endpoints outside the SDK:

* Read the OAuth section of the [Quickstart](/quickstart) to mint tokens with PKCE.
* Send `Authorization: Bearer <access_token>` headers on every request.
* Provide `Humanity-Client-Id` (optional) when you need explicit attribution across multiple client IDs.

The OpenAPI `security` block mirrors these requirements so generators and lint rules can enforce them automatically.