# PlatformPilot Developer Portal

> Everything you need to build on the PlatformPilot company brain: the REST API and its OpenAPI spec, the Brain MCP server, OAuth 2.0 discovery, rate limits, and the versioning policy. Every page on this site also serves Markdown to agents.

Canonical URL: https://platformpilot.ai/developers

## Start here

- [Agents API reference](https://api.platformpilot.ai/docs): Interactive reference for every REST operation.
- [Agents API OpenAPI 3.1 spec](https://api.platformpilot.ai/openapi.json): Machine-readable. 412 operations, each with an operationId and description.
- [Brain MCP server](https://mcp.platformpilot.ai/brain/mcp): Streamable HTTP transport, OAuth 2.1 with PKCE and dynamic client registration.
- [MCP gateway](https://mcp.platformpilot.ai/): Index of every hosted MCP server, with llms.txt, auth.md (how an agent obtains credentials), an ARD catalog, and a server card per server.
- [Agent setup prompt](https://platformpilot.ai/agent-setup/prompt.md): Paste into Claude Code, Cursor, Codex, Windsurf, OpenCode, Copilot, or Claude Desktop; the agent wires itself up.
- [Web API OpenAPI spec](https://platformpilot.ai/openapi.json): The public, unauthenticated endpoints on platformpilot.ai (blog feed, search, status, discovery files).
- [OAuth 2.0 authorization server metadata](https://platformpilot.ai/.well-known/oauth-authorization-server): RFC 8414 discovery document for the PlatformPilot authorization server.
- [llms.txt](https://platformpilot.ai/llms.txt): Agent-oriented site summary with when-to-use guidance.
- [Dashboard](https://dash.platformpilot.ai): Create an account, manage your organization, and issue API credentials.
- [Status](https://status.platformpilot.ai): Live platform status with a JSON API.
- [GitHub](https://github.com/dyngai): Open source from the PlatformPilot team.

## Quickstart: connect an agent to the brain

1. Create an account at [https://platformpilot.ai/get-started](https://platformpilot.ai/get-started). Sign-up is self-serve with email or Google; the onboarding flow creates your organization and its brain.
2. Register the Brain MCP server with your agent. The fastest path is to paste [https://platformpilot.ai/agent-setup/prompt.md](https://platformpilot.ai/agent-setup/prompt.md) into the agent and let it run the steps below itself.
3. Sign in when the OAuth window opens on first tool use. Tokens are scoped per client and can be revoked from the dashboard.
4. Recall before you write: call `recall_context` or `search_memories` at the start of a task, record what you learned with `manage_memories` when you finish, and report how the recalled memories worked with `feedback_memories`.

`Claude Code`

```bash
claude mcp add platformpilot-brain --transport http --url https://mcp.platformpilot.ai/brain/mcp
```

`claude_desktop_config.json (also Cursor .cursor/mcp.json and Copilot .vscode/mcp.json)`

```json
{
  "mcpServers": {
    "platformpilot-brain": { "url": "https://mcp.platformpilot.ai/brain/mcp" }
  }
}
```

`OpenAI Agents SDK`

```python
from agents import Agent
from agents.mcp import MCPServerStreamableHttp

brain = MCPServerStreamableHttp(params={"url": "https://mcp.platformpilot.ai/brain/mcp"})
agent = Agent(name="my-agent", mcp_servers=[brain])
```

## Brain MCP server

The brain is exposed as a Model Context Protocol server at `https://mcp.platformpilot.ai/brain/mcp` over the Streamable HTTP transport. It is the same memory PlatformPilot's own agents read and write, so anything your agent records is visible to every other client connected to your organization.

| Tool | What it does |
| --- | --- |
| `recall_context` | Compose context for a task in one call: topic search, entity lookup, and specific memory keys together. |
| `search_memories` | Semantic search over past events (episodes) or reusable learnings (knowledge); each result carries a warning when the memory recently failed in use. |
| `fetch_memories` | Read memories by exact key, or resolve a flagged contradiction or open question by its id. |
| `manage_memories` | Create, update, or delete a memory in either namespace. |
| `feedback_memories` | Report whether work that relied on the listed memories worked or failed, so later reads rank and warn accordingly. |

Authentication follows the MCP authorization specification: an unauthenticated `initialize` returns `401` with a `WWW-Authenticate` challenge, the protected resource metadata names the authorization server, and clients register dynamically and complete an authorization-code flow with PKCE (S256).

- [Protected resource metadata (RFC 9728)](https://mcp.platformpilot.ai/.well-known/oauth-protected-resource/brain/mcp)
- [MCP authorization server metadata (RFC 8414)](https://mcp.platformpilot.ai/brain/.well-known/oauth-authorization-server)
- [Gateway auth.md (credential walkthrough)](https://mcp.platformpilot.ai/auth.md)
- [Gateway index and llms.txt](https://mcp.platformpilot.ai/llms.txt)

Tool listing requires a signed-in organization because tool availability depends on plan entitlements. The five tools above are the core public surface. Organizations with the entity graph enabled also see `explain_entity`, `entity_path`, and `affected_entities`, which explore how the people, systems, and organizations in the brain relate, citing the memory that asserted each relationship.

## REST API

The Agents API at `https://api.platformpilot.ai` is the system of record behind the dashboard: organizations, users, teams, memory graph and memory seeding, investigations (threads and runs), scheduled jobs, playbooks, integrations and MCP configuration, webhooks, alerts, billing, and evaluation. The OpenAPI 3.1 document lists 412 operations across 316 paths; every operation has a unique `operationId`, a description, typed parameters, and response schemas.

- [OpenAPI document](https://api.platformpilot.ai/openapi.json)
- [Interactive reference](https://api.platformpilot.ai/docs)
- [Health check](https://api.platformpilot.ai/health): Unauthenticated liveness endpoint.

`Example: list your organizations`

```bash
curl -s https://api.platformpilot.ai/organizations \
  -H "Authorization: Bearer $PLATFORMPILOT_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

The public Web API on `https://platformpilot.ai` is separate and needs no credentials: a JSON blog feed, semantic blog search, platform status, and the discovery files listed on this page. It is described by [https://platformpilot.ai/openapi.json](https://platformpilot.ai/openapi.json) and indexed at [https://platformpilot.ai/api](https://platformpilot.ai/api).

## Authentication

PlatformPilot uses OAuth 2.0. The authorization server is `https://auth.platformpilot.ai/` and its metadata is published at [https://platformpilot.ai/.well-known/oauth-authorization-server](https://platformpilot.ai/.well-known/oauth-authorization-server) (also mirrored as [OpenID Provider configuration](https://platformpilot.ai/.well-known/openid-configuration)). Access tokens for the REST API are JWTs issued for the audience `https://api.platformpilot.ai`; send them as `Authorization: Bearer <token>`.

- **Interactive clients** (MCP clients, CLIs, dashboards): authorization code flow with PKCE (`S256`). MCP clients discover the server through the protected resource metadata and may register dynamically at the `registration_endpoint`.
- **Server-to-server**: `client_credentials` with a confidential client issued for your organization.
- **API keys**: operations in the Agents API spec also accept an `x-api-key` header. Keys are created from the [dashboard](https://dash.platformpilot.ai) for your organization and should be treated like passwords: rotate from the same place.
- **Machine payments**: the Brain can sell access passes to autonomous agents through the Machine Payments Protocol. `POST https://platformpilot.ai/api/agent/brain-pass` answers `402` with a signed `WWW-Authenticate: Payment` challenge and settles on retry.

Never embed user tokens in prompts or logs. Tokens are short-lived; refresh tokens are only issued when `offline_access` is requested and are bound to the client that obtained them.

## Rate limits

Every Web API response carries the IETF `RateLimit` and `RateLimit-Policy` headers, the widely used `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` names, and an `API-Version` header. Throttled requests return `429 Too Many Requests` as an RFC 9457 problem document with `Retry-After` set to the seconds until the window resets. Limits are per client IP and per policy.

| Policy | Applies to | Limit |
| --- | --- | --- |
| `public-read` | `/api/v1/blog/posts`, `/api/v1/blog/posts/{slug}`, `/api/v1/platform-status`, `/api` | 60 requests per 60 seconds |
| `blog-search` | `/api/v1/blog/search` | 30 requests per 60 seconds |

`Example response headers`

```http
RateLimit-Policy: "public-read";q=60;w=60
RateLimit: "public-read";r=57;t=43
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 43
API-Version: 1
```

Limits on the Agents API depend on your plan (Professional raises the webhook event limits, for example) and are enforced per organization. Throttled requests return `429`; honor `Retry-After` when present and back off exponentially otherwise.

## Versioning and deprecation policy

- **Web API**: versioned in the URL path. `/api/v1/` is the current major version and every response carries `API-Version: 1`. The unversioned `/api/...` paths are aliases of v1 and will keep resolving to v1 even after a v2 ships.
- **Agents API**: versioned with semantic versioning in `info.version` of the OpenAPI document (currently 1.0.0). Additive changes (new operations, new optional fields, new enum values) ship within a major version. Breaking changes only ship under a new major version at a new base path, and the previous major keeps working for the deprecation window.
- **Deprecation signalling**: an operation scheduled for removal is marked `deprecated: true` in the OpenAPI document and its responses carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with the removal date, at least 90 days ahead. The replacement is linked with `Link: <...>; rel="successor-version"`.
- **Where changes are announced**: the [blog](https://platformpilot.ai/blog) (category Product or Engineering), the status page, and the OpenAPI documents themselves. Agents can diff [https://api.platformpilot.ai/openapi.json](https://api.platformpilot.ai/openapi.json) to detect changes.

## Agent-friendly site conventions

- **Markdown content negotiation**: request any page with `Accept: text/markdown` and you get `text/markdown; charset=utf-8` with `Vary: Accept`. Quality values are honored, an `Accept` that excludes both HTML and Markdown gets `406`, and every HTML response advertises its twin with `Link: <...>; rel="alternate"; type="text/markdown"`.
- **Markdown siblings**: append `.md` to a page path (`/about.md`, `/blog/<slug>.md`, `/index.md` for the home page) to fetch the Markdown without a special header.
- **llms.txt**: [https://platformpilot.ai/llms.txt](https://platformpilot.ai/llms.txt) summarizes the product, lists when to use it, and links every machine-readable surface. [https://platformpilot.ai/llms-full.txt](https://platformpilot.ai/llms-full.txt) is the long form.
- **Blog feed**: [https://platformpilot.ai/api/v1/blog/posts](https://platformpilot.ai/api/v1/blog/posts) lists posts with agent summaries, when-to-use notes, key claims, and related concepts; `/api/v1/blog/posts/{slug}` adds the full text.
- **404s**: unknown paths return a real HTTP 404. With `Accept: text/markdown` the body is a short Markdown site map pointing at [https://platformpilot.ai/sitemap.xml](https://platformpilot.ai/sitemap.xml), llms.txt, and this page.
- **Discovery files**: [robots.txt](https://platformpilot.ai/robots.txt), [sitemap.xml](https://platformpilot.ai/sitemap.xml), [openapi.json](https://platformpilot.ai/openapi.json), [.well-known/oauth-authorization-server](https://platformpilot.ai/.well-known/oauth-authorization-server).

`Verify from a terminal`

```bash
curl -sI -H "Accept: text/markdown" https://platformpilot.ai/ | grep -iE "^(content-type|vary)"
curl -s -o /dev/null -w "%{http_code}\n" https://platformpilot.ai/a-path-that-does-not-exist
curl -s https://platformpilot.ai/.well-known/oauth-authorization-server | jq .issuer
```

## Free trial, plans, and sandbox

- **Self-serve**: sign up at [https://platformpilot.ai/get-started](https://platformpilot.ai/get-started) with email or Google. No sales call is required for Starter or Professional.
- **Trial**: when a plan carries a trial it is offered at checkout with the length shown before you confirm; the Brain MCP server is available during the trial. Plans and prices are listed at [https://platformpilot.ai/#explore-plans](https://platformpilot.ai/#explore-plans).
- **Isolation**: every organization runs in its own isolated setup, so a second organization is a safe place to experiment. There is no separate public sandbox environment today; for an evaluation tenant with seeded data, book a demo.
- **Billing regions**: customers in the EU, EEA, UK, and Switzerland are billed by PlatformPilot Limited in EUR; everyone else by DynG AI, Inc. in USD. Region is detected at checkout.

## Support

- [support@platformpilot.ai](mailto:support@platformpilot.ai): Technical support for API, MCP, and account questions.
- [Contact](https://platformpilot.ai/contact): Sales, support, and press.
- [Book a demo](https://platformpilot.ai/contact-sales)
- [Status](https://status.platformpilot.ai)
- [About the company](https://platformpilot.ai/about)