Carbon for developers

Quick start

Create a scoped API key in Settings → API Keys, then send it on every request as Authorization: Bearer <api-key>. The carbon-key header works identically.

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

A key belongs to one company and carries an explicit set of module permissions. Row-level security in the database — not just the application — confines every request to that scope, so a key can only ever touch the data it was granted.

Every key allows 60 requests per minute. A refused request returns 429 with Retry-After and X-RateLimit-* headers — back off on those rather than retrying immediately.

OAuth 2.0

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

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

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

Connect an agent over MCP

The Carbon MCP server speaks the Streamable HTTP transport at https://app.carbon.ms/api/mcp. It authenticates with the same API key as a bearer token, or with OAuth. Its manifest is at /.well-known/mcp.json.

{
  "mcpServers": {
    "carbon": {
      "type": "http",
      "url": "https://app.carbon.ms/api/mcp",
      "headers": { "Authorization": "Bearer <api-key>" }
    }
  }
}

The server exposes three tools — search_tools, describe_tool and call_tool — that reach more than 1,400 ERP operations across 15 modules, each classified read, write or destructive. The MCP guide covers the details.

Resources

• Carbon API documentation — Generated reference for every REST resource: endpoints, attributes, request and response shapes, and copy-paste examples.
• Carbon OpenAPI specification — 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 — The API itself. Every table Carbon exposes is a resource, governed by the same row-level security as the app.
• Carbon MCP server — 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 — How to connect an agent to Carbon over MCP, including the available tools and their permission scopes.
• Carbon API authentication — Creating a scoped API key and sending it as `Authorization: Bearer <api-key>` (or the `carbon-key` header).
• Carbon webhooks and integrations — Event-driven integrations, webhook payloads, and the first-party connectors (Onshape, QuickBooks, Xero, Slack, Jira, Linear, Paperless Parts).
• Carbon source code — The Carbon monorepo. The whole ERP, MES and QMS, self-hostable, under a source-available license.
• Carbon agent guidance (llms.txt) — Where an agent should start: what Carbon is, and the canonical URL for every product surface.
• Carbon system status — Live availability and incident history for the hosted product.

Machine-readable files

Served from this domain, unauthenticated, with CORS open so a browser-based agent can read them:

• /openapi.json — OpenAPI 3.1 description of the Carbon REST API.
• /openapi.yaml — The same document, as YAML.
• /.well-known/mcp.json — MCP server manifest — transport, endpoint, and auth.
• /llms.txt — Where an agent should start, and the canonical URL for each surface.
• /sitemap.xml — Every page on this site.

Every page on carbon.ms is also available as Markdown: send Accept: text/markdown, or append .md to the path.