Humanity Developer Platform API v2

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/api/v1

• Production: https://api.humanity.org/api/v1

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

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