# 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/de1bb8d81d08ced16634c41335a47e725414bb19/" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humanity.org/api-reference/humanity-developer-platform-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.