> For the complete documentation index, see [llms.txt](https://docs.humanity.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humanity.org/api-reference/humanity-developer-platform-api.md).
# 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.
View OpenAPI spec
***
### 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
```
✅ Optional attribution header
* Provide this when you need explicit attribution across multiple client IDs:
```
Humanity-Client-Id:
```
> ℹ️ The OpenAPI security block mirrors these requirements so generators and lint rules can enforce them automatically.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.humanity.org/api-reference/humanity-developer-platform-api.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.