# The Org

> The Org operates the world's largest network of public organizational charts, mapping companies, their teams, and reporting hierarchies. Its developer platform exposes a metered REST API and an official remote MCP server for looking up a company's org chart, searching companies and people, prospecting positions, resolving work emails, walking reporting lines, and managing lead lists. Authentication is an account-scoped `X-Api-Key` header over HTTPS; usage is metered in credits shared across REST and MCP.

Generated by API Evangelist from https://developers.theorg.com — The Org publishes no llms.txt of its own (probed 2026-08-14: developers.theorg.com/llms.txt, theorg.com/llms.txt, api.theorg.com/llms.txt all 404).

## Key facts

- REST base URL: `https://api.theorg.com/v1.1` (org-chart endpoint is on `/v1.2`)
- MCP endpoint: `POST https://api.theorg.com/v1.1/mcp` (Streamable HTTP, JSON-RPC 2.0)
- Auth: `X-Api-Key: <key>`, HTTPS required. Same key for REST and MCP.
- No OpenAPI, no GraphQL, no webhooks, no A2A agent card, no SDKs in any language.
- Rate limit: 15 requests/second per endpoint across all keys on an account; `429` on exceed, no `Retry-After` header.
- Credits: metered per operation, shared between REST and MCP. `402` when exhausted.
- Errors: `{"error":{"code":<status>,"reason":"<text>"}}` — not RFC 9457.
- No idempotency-key contract. The 24h "replay" rule is billing dedup, not write safety.
- No status page and no SLA.

## APIs

- [Company API](https://developers.theorg.com/api/endpoints/company-api): `GET /v1.2/companies/org-chart` by domain or LinkedIn URL (10 credits); `GET /v1.1/companies/org-chart/managers` by email or LinkedIn URL (1 credit).
- [Position API](https://developers.theorg.com/api/endpoints/position-api): `POST /v1.1/positions` filtered people/position search, required `limit` (max 1000) + `offset` (max 10000), 1 credit per returned row; `POST /v1.1/positions/credit-usage` free cost estimate.
- [Lists API](https://developers.theorg.com/api/endpoints/lists-api): `GET /v1.1/lists` read-only people/lead lists, `limit` 1–100 (default 30) + `offset`. Free.
- [Usage API](https://developers.theorg.com/api/endpoints/usage-api): `GET /v1.1/usage` current credits; `GET /v1.1/usage/history` per-API daily/monthly series. Free.
- [MCP API](https://developers.theorg.com/api/endpoints/mcp-api): 13 tools, listed below.

## MCP tools

Free: `search_companies`, `get_company`, `get_org_chart` (returns a signed iframe embed URL, not JSON), `find_person`, `find_jobs` (max 25), `get_lists`, `add_to_list` (max 25 IDs), `create_list` (max 25 IDs), `get_usage`.

Metered: `get_manager` (1/find), `get_reports` (1 when found, max 50), `find_positions` (1/row, max 25), `resolve_contacts` (1 per newly resolved, max 25).

The MCP surface is wider than REST: 8 of 13 tools have no REST equivalent, and `create_list`/`add_to_list` are the only write operations The Org exposes anywhere.

## Docs

- [Developer portal](https://developers.theorg.com/)
- [API overview](https://developers.theorg.com/api)
- [Get started](https://developers.theorg.com/api/get-started)
- [Key concepts](https://developers.theorg.com/api/key-concepts) — auth, rate limits, credits, errors
- [Change log](https://developers.theorg.com/api/change-log)
- [MCP introduction](https://developers.theorg.com/mcp) and [MCP get started](https://developers.theorg.com/mcp/get-started)
- [Data models](https://developers.theorg.com/api/data-models/company): company, location, org-chart, position
- [Embed org charts](https://developers.theorg.com/embed)
- [Zapier connector](https://developers.theorg.com/zapier)
- [Flat files](https://developers.theorg.com/flat-files) — monthly gzipped LDJSON snapshots over SFTP, access on request
- [Pricing](https://theorg.com/pricing)
- [Trust center](https://theorg.com/trust)
- [Support](https://support.theorg.com/en/)

## Authorization discovery

- [OAuth authorization server metadata](https://api.theorg.com/.well-known/oauth-authorization-server) (RFC 8414)
- [OAuth protected resource metadata](https://api.theorg.com/.well-known/oauth-protected-resource) (RFC 9728)

An OAuth 2.1 authorization server (authorization code + PKCE S256, dynamic client registration, scope `mcp`) protects the MCP endpoint. It is live and discoverable but appears in no documentation page and no changelog entry; the docs describe `X-Api-Key` only.

## API Evangelist artifacts

- [apis.yml](https://raw.githubusercontent.com/api-evangelist/theorg/refs/heads/main/apis.yml)
- authentication/theorg-authentication.yml
- scopes/theorg-scopes.yml
- conventions/theorg-conventions.yml
- errors/theorg-problem-types.yml
- rate-limits/theorg-rate-limits.yml
- plans/theorg-plans-pricing.yml
- lifecycle/theorg-lifecycle.yml
- changelog/theorg-changelog.yml
- data-model/theorg-data-model.yml
- mcp/theorg-mcp.yml and mcp/theorg-tool-crosswalk.yml
- well-known/theorg-well-known.yml
- conformance/theorg-conformance.yml
- components/theorg-components.yml
- packages/theorg-packages.yml
- security/theorg-domain-security.yml and security/theorg-trust-center.yml
- skills/_index.yml