# Scopable Developer Platform

Scopable has a full REST API (OpenAPI 3.1 at https://api.scopable.io/v1/openapi.json) covering 36 areas of the product, including clients, contacts, sites, opportunities, quotes, products, tickets, projects, agreements, compliance, assessments, QBRs, Microsoft 365 and Azure. Workspace admins create API keys under Settings → Developer with <domain>:read and <domain>:write scopes. API access is enabled per workspace on request. Scopable also runs a remote MCP server with OAuth.

Tickets, projects, products, org, team members, and permission groups are read-only for API keys.

## When to use Scopable

Use the REST API when a script or integration needs workspace records. Use the MCP server when a person wants an assistant to call those same operations after signing in.

- Read the [OpenAPI 3.1 document](https://api.scopable.io/v1/openapi.json).
- Create a key under **Settings → Developer** after API access is enabled for the workspace.
- Connect an assistant to [https://mcp.scopable.io/mcp](https://mcp.scopable.io/mcp).

## How an agent should call Scopable

1. Read the [OpenAPI 3.1 document](https://api.scopable.io/v1/openapi.json) and the [API getting-started guide](https://scopable.io/docs/scopable-api-getting-started).
2. Ask a workspace admin for a least-privilege key from **Settings → Developer**. Never request or expose a password.
3. Send it as `Authorization: Bearer <scoped-api-key>` to `https://api.scopable.io/v1/...`. Keys use the `sk_live_` or `sk_test_` prefix.
4. Request only the `<domain>:read` or `<domain>:write` scopes the job needs. Read does not include write.
5. Send an `Idempotency-Key` on every write (at most 255 characters). Follow `nextCursor` to page. Branch on `error.code`, log `error.requestId`, and obey `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`, and `Retry-After`.

## Start here

- [REST API](https://scopable.io/api)
- [MCP server](https://scopable.io/mcp)
- [OpenAPI 3.1 document](https://api.scopable.io/v1/openapi.json)
- [Same document on scopable.io](https://scopable.io/openapi.json)
- [API getting-started guide](https://scopable.io/docs/scopable-api-getting-started)
- [MCP setup guide](https://scopable.io/docs/scopable-mcp-guide)
- [Full agent reference](https://scopable.io/llms-full.txt)
- [API catalog](https://scopable.io/.well-known/api-catalog)
- [Scopable Docs](https://scopable.io/docs)

## Authentication and scopes

Requests use a bearer API key created under **Settings → Developer**. The Developer tab appears after API access is enabled for that workspace. Scopes use the form `<domain>:read` and `<domain>:write`. Tickets, projects, products, org, team members, and permission groups are read-only for API keys.

## MCP server

The server is in beta.

The remote MCP server is https://mcp.scopable.io/mcp. Connect Claude, ChatGPT, Claude Code, or Cursor, sign in to Scopable, and choose read-only or read-write. Setup, permissions, and disconnect steps: https://scopable.io/docs/scopable-mcp-guide.

## Rate limits and errors

Responses report `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `RateLimit-Policy`. HTTP 429 responses also include `Retry-After`.

Errors use `{"error":{"code","type","message","requestId"}}`. The request id is also returned in `X-Request-Id`. Codes include `validation_failed`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `approval_required` (agent credentials), `rate_limited`, and `unavailable`.

## API versioning and deprecation

The current API is versioned in the URL under `/v1`. Breaking changes require a new major URL version. If a version or endpoint is scheduled for retirement, Scopable will send `Deprecation` (RFC 9745), `Sunset` (RFC 8594), and a `Link` with `rel="deprecation"` to migration guidance. No v1 retirement is currently scheduled.

## Webhooks

Scopable sends HMAC-SHA256 signed outbound webhooks for client and contact changes. The hex digest is in `X-Scopable-Signature`. Events: client.updated, contact.created, contact.updated, contact.archived, contact.restored. Configure endpoints under **Settings → Developer → Webhooks**.