# Carbon developers: API, MCP server and OpenAPI spec

Everything needed to build against Carbon: the REST API, the MCP server, the
OpenAPI specification, webhooks, and the source code.

## Get a Carbon API key

Self-serve from start to first request — no sales call, no form.

1. Sign up at https://app.carbon.ms and start the 30-day free trial — no sales call. Choose the Business plan: the API, webhooks and the MCP server are Business features.
2. Generate a scoped API key yourself in Settings → API Keys (https://app.carbon.ms/x/settings/api-keys). Keys are self-serve, scoped to one company and to the module permissions you choose.
3. Call the REST API at https://rest.carbon.ms or connect an agent to the MCP server at https://app.carbon.ms/api/mcp with that key.

These need no credential at all:

- https://carbon.ms/openapi.json
- https://carbon.ms/.well-known/mcp.json
- https://carbon.ms/llms.txt
- https://carbon.ms/.well-known/oauth-protected-resource
- https://carbon.ms/developers.md

The Community Edition is free to self-host from https://github.com/crbnos/carbon.

## Carbon API quick start

1. Create a scoped API key in Settings → API Keys at
   [https://app.carbon.ms/x/settings/api-keys](https://app.carbon.ms/x/settings/api-keys).
2. Send it on every request as `Authorization: Bearer <api-key>` (the
   `carbon-key` header works identically).
3. Call a resource:

```bash
curl 'https://rest.carbon.ms/item?limit=1' \
  -H "Authorization: Bearer <api-key>"
```

The key is scoped to one company and to the module permissions you check when
creating it, and the database enforces those scopes with row-level security —
not just the application layer.

Every key allows 60 requests per minute. A refused request returns `429` with
`Retry-After` (seconds), `X-RateLimit-Limit`, `X-RateLimit-Remaining` and
`X-RateLimit-Reset` (Unix milliseconds). Back off on those rather than
retrying immediately.

## Carbon API OAuth 2.0

An agent that cannot hold a long-lived key can obtain a token instead.
[https://app.carbon.ms](https://app.carbon.ms) is the authorization server; its metadata is published
at [`/.well-known/oauth-authorization-server`](https://app.carbon.ms/.well-known/oauth-authorization-server)
(RFC 8414), and protected-resource metadata at
[`/.well-known/oauth-protected-resource`](https://app.carbon.ms/.well-known/oauth-protected-resource)
(RFC 9728). Both paths on `carbon.ms` redirect to them, so either origin
resolves.

The MCP endpoint returns `401` with
`WWW-Authenticate: Bearer resource_metadata="..."` pointing at the same
document, which is the discovery path a compliant MCP client follows on its own.

## Carbon API versioning and deprecation

- The OpenAPI document is versioned by `info.version`, semver. It is served from a stable URL (`/openapi.json`) and its version is bumped whenever the published contract changes.
- A breaking change to a published operation — a removed operation, a removed or retyped field, a new required parameter — bumps the MAJOR. Additive changes bump the MINOR.
- Nothing is removed without notice. An operation that is going away is first marked `deprecated: true` in the OpenAPI document, with `x-deprecated-at` (the date it was deprecated) and `x-sunset` (the earliest date it may be removed, at least 90 days later), in a MINOR release. Every operation declares `deprecated` explicitly, so a diff of the spec shows the change.
- The REST API itself carries no version segment in its URL today: resources are addressed directly (`/item`, `/salesOrder`). Pin the spec version you built against, and diff `info.version` before upgrading.

## Carbon MCP server

Carbon's MCP server speaks the Streamable HTTP transport at
[https://app.carbon.ms/api/mcp](https://app.carbon.ms/api/mcp). It authenticates with the same API key (as a bearer
token) or with OAuth. The machine-readable manifest is at
[https://carbon.ms/.well-known/mcp.json](https://carbon.ms/.well-known/mcp.json).

## Carbon developer resources

- [Carbon API documentation](https://docs.carbon.ms/api) — Generated reference for every REST resource: endpoints, attributes, request and response shapes, and copy-paste examples.
- [Carbon OpenAPI specification](https://carbon.ms/openapi.json) — Machine-readable OpenAPI 3.1 description of the Carbon REST API, with an operationId, a description and typed response schemas on every operation. Also served as YAML at /openapi.yaml.
- [Carbon REST API](https://rest.carbon.ms) — The API itself. Every table Carbon exposes is a resource, governed by the same row-level security as the app.
- [Carbon MCP server](https://app.carbon.ms/api/mcp) — Model Context Protocol endpoint over Streamable HTTP, so Claude, ChatGPT and other agents can call Carbon natively. Manifest at /.well-known/mcp.json.
- [Carbon MCP guide](https://docs.carbon.ms/api/mcp) — How to connect an agent to Carbon over MCP, including the available tools and their permission scopes.
- [Carbon API authentication](https://docs.carbon.ms/api/authentication) — Creating a scoped API key and sending it as `Authorization: Bearer <api-key>` (or the `carbon-key` header).
- [Carbon webhooks and integrations](https://docs.carbon.ms/integrations) — Event-driven integrations, webhook payloads, and the first-party connectors (Onshape, QuickBooks, Xero, Slack, Jira, Linear, Paperless Parts).
- [Carbon source code](https://github.com/crbnos/carbon) — The Carbon monorepo. The whole ERP, MES and QMS, self-hostable, under a source-available license.
- [Carbon agent guidance (llms.txt)](https://carbon.ms/llms.txt) — Where an agent should start: what Carbon is, and the canonical URL for every product surface.
- [Carbon system status](https://status.carbon.ms) — Live availability and incident history for the hosted product.

## Elsewhere on carbon.ms

- [Agent guidance](https://carbon.ms/llms.txt)
- [Developer resources](https://carbon.ms/developers)
- [OpenAPI specification](https://carbon.ms/openapi.json)
- [MCP manifest](https://carbon.ms/.well-known/mcp.json)
- [Sitemap](https://carbon.ms/sitemap.xml)