# API First

> **Info: As a core [engineering principle](https://github.com/epilot-dev/engineering-principles#api-first-we-design-software-with-apis), epilot designs API contracts before implementation.**

All APIs are defined using machine-readable standards:

- [OpenAPI specification](https://www.openapis.org/)
- [TypeScript type definitions](https://www.typescriptlang.org/)

## Public API

All core APIs are public. Partners and customers use them to build integrations and extend the platform.

<a className="button button--secondary" href="/api">Browse the API Reference</a>

<a className="button button--secondary" href="/api/changelog">API Changelog</a>

## Webhooks & Event Schemas

epilot publishes platform events through [Webhooks](/docs/integrations/webhooks), enabling real-time push notifications to external systems. Events follow a standardized schema defined in [Core Events](/docs/integrations/core-events), covering entity lifecycle changes, workflow transitions, portal actions, and more.

Webhooks are the primary mechanism for outbound integrations — ERPs, middleware, and third-party systems subscribe to the events they care about and receive structured payloads as they happen. See [Payload Structure](/docs/integrations/webhooks/payload-structure/intro) for format details and [Security](/docs/integrations/webhooks/security) for signature verification.

## API Versioning & Compatibility

epilot maintains strong backwards compatibility commitments for all public APIs. See the [API Versioning](/api#versioning) section for details on compatibility guarantees, deprecation policies, and what constitutes a breaking change.

## Accessing APIs with MCP

> **Tip: Developers using LLM clients (Claude Desktop, Cursor, etc.) can explore epilot APIs interactively through the [MCP](https://modelcontextprotocol.io/) server — no manual API doc browsing required.**

### Setup

Add this to your MCP client configuration (see [MCP setup guide](https://modelcontextprotocol.io/quickstart/user)):

```json title="MCP client config"
{
  "mcpServers": {
    "epilot-openapi": {
      "command": "npx",
      "args": ["-y", "openapi-analyzer-mcp"],
      "env": {
        "OPENAPI_DISCOVERY_URL": "https://docs.epilot.io/openapi-specs/apis.json"
      }
    }
  }
}
```

### Usage

Once configured, you can:

- Query available endpoints and schemas
- Explore request/response formats interactively
- Generate code examples for specific endpoints