# Humanity Developer Platform API

Welcome to the **Humanity Developer Platform API v2**.

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

<a href="https://gist.githubusercontent.com/andrei-humanity/ac34436543a1a2c944d545db4413cc7c/raw/9bdbb354d77d8c3bafd2fefa88674dd0f2d3689f/dev%20api%20openapi" class="button primary" data-icon="arrow-up-right-from-square">View OpenAPI spec</a><br>

***

### Base URLs & Authentication

#### Base URLs

* **Sandbox:** `https://api.sandbox.humanity.org/v2/`
* **Production:** `https://api.humanity.org/v2/`

#### Requirements

* All endpoints require **HTTPS**
* All endpoints require **Bearer tokens**

#### OAuth flows

* **Public clients:** OAuth 2.1 + PKCE
  * `code_challenge_method = S256`
* **Service-to-service:** confidential client credentials (where approved)

#### OpenAPI security block

```json
"security":[{"bearerAuth":[]}]
```

***

### Resources at a Glance

Each page under:

* **OAuth & Consent**
* **Feeds & Access**
* **Discovery & Health**

…maps directly to an **OpenAPI operation**.

How to use the interactive reference:

1. Set the **server dropdown** (sandbox or production)
2. Click **Try it**
3. Execute real requests using your **bearer token**

***

### Working With the Spec

1. Download the JSON file
2. Import it into your API tooling

#### Common options

* **Postman / Insomnia** → manual testing
* **Stoplight Studio** or **VS Code OpenAPI viewers** → schema exploration
* **openapi-generator / orval** → generate a client in another language

#### Versioning & changes

* Watch the **`version`** field in the spec
* Humanity increments it whenever contracts change
* DevRel announcements include:
  * release notes
  * deprecation windows

***

### Authentication Reminders

All operations require:

* **HTTPS**
* a valid **access token**

If calling endpoints outside the SDK:

✅ **Mint tokens with PKCE**

* See the OAuth section of the Quickstart

✅ **Send this header on every request**

```
Authorization: Bearer <access_token>
```

✅ Optional attribution header

* Provide this when you need explicit attribution across multiple client IDs:

```
Humanity-Client-Id: <client_id>
```

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