ChapterTwo Documentation

ChapterTwo is a music royalty management platform. This documentation covers the tools and APIs available for integrating with ChapterTwo programmatically.

Integration Methods

Choose the integration method that fits your workflow:

Method	Best For	Install
API + SDK	Building custom integrations	npm install @chapter-two-music/sdk
CLI	Command-line workflows and scripting	npm install -g @chapter-two-music/cli
MCP	AI assistant integrations (Claude, Cursor)	No install — connect via URL

Authentication

All integration methods use the same authentication system. Two options are available:

OAuth 2.0 (recommended)

OAuth 2.0 with PKCE is the default authentication method. The CLI and MCP server handle the flow automatically. For direct API usage, use the OAuth endpoints:

Endpoint	URL
Authorization	https://mcp.chaptertwo.com/api/oauth/authorize
Token	https://mcp.chaptertwo.com/api/oauth/token
Discovery	https://mcp.chaptertwo.com/.well-known/oauth-authorization-server

The OAuth flow issues an access token (valid for 1 hour) and a refresh token (valid for 30 days). Your application should refresh the access token before it expires. See the API Reference for details on token lifecycle and refresh.

API Keys

For service-to-service integrations, use an API key. API keys do not expire and are suitable for long-running automated workflows.

API keys must be requested from ChapterTwo. Contact your account manager or email support@chaptertwo.com to request an API key for your organization.

Include the API key in the x-api-key header along with the x-organization-id header:

bash
curl -H "x-api-key: YOUR_API_KEY" \
     -H "x-organization-id: YOUR_ORG_ID" \
     https://api.prod.chaptertwo.com/trpc/health

Organizations

All data in ChapterTwo is scoped to an organization. When making API calls, you must specify which organization you are acting on behalf of. The organizationId field is required in the input for most endpoints.

If you belong to multiple organizations, select one via the x-organization-id header or the organizationId input field.

Base URLs

Service	URL
API	https://api.prod.chaptertwo.com
MCP Server	https://mcp.chaptertwo.com/api/mcp
OAuth Discovery	https://mcp.chaptertwo.com/.well-known/oauth-authorization-server

Error Handling

The API uses tRPC error format. All errors include a message, numeric code, and a string error code:

json
[{
  "error": {
    "message": "Rightsholder not found",
    "code": -32004,
    "data": {
      "code": "NOT_FOUND",
      "errorCode": "RIGHTSHOLDER_NOT_FOUND"
    }
  }
}]

Common error codes:

—NOT_FOUND — The requested resource does not exist
—UNAUTHORIZED — Missing or invalid authentication
—FORBIDDEN — Insufficient permissions
—BAD_REQUEST — Invalid input parameters
—CONFLICT — Resource already exists or state conflict

Rate Limits

The API is hosted on AWS API Gateway with standard throttling. Contact support if you need higher limits for your integration.