API Reference

REST API v1

Quick Start

Base URL:        https://cpam.app/api/v1
Authentication:  Bearer token (Authorization: Bearer YOUR_API_KEY)
Content-Type:    application/json
Rate limit:      60 requests / minute per key

API keys are created in Settings → API Keys. Keys are shown once — store them securely.

Authentication

All endpoints except /api/v1/health require a Bearer token in the Authorization header:

Authorization: Bearer cpam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Requests without a valid token return 401 Unauthorized. Invalid or expired tokens also return 401.

Rate limit exceeded returns 429 Too Many Requests with a Retry-After header.

Endpoints

GET/api/v1/healthNo authentication required

Simple ping and uptime check. Returns the API status and current server timestamp. Use this endpoint to verify connectivity before making authenticated requests.

Example Response

{
  "status": "ok",
  "version": "v1",
  "timestamp": "2026-05-16T12:00:00.000Z"
}

GET/api/v1/series

List index series visible to your workspace. Results are paginated using cursor-based pagination. Use the nextCursor value from a previous response to fetch the next page.

Parameters

Parameter	Type	Required	Description
`provider`	string	No	Filter by provider (BLS, FRED, EIA, ECB, WORLD_BANK, ALPHA_VANTAGE, IMF, EUROSTAT, ONS, OANDA, STATCAN, ABS, USDA, BIS)
`limit`	integer	No	Results per page. Default: 50. Max: 200.
`cursor`	string	No	Pagination cursor from a previous response's pagination.nextCursor.

Example Request

curl https://cpam.app/api/v1/series?provider=BLS&limit=10 \
  -H "Authorization: Bearer cpam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "cser_01jz...",
      "seriesCode": "CUUR0000SA0",
      "name": "CPI All Urban Consumers",
      "provider": "BLS",
      "dataType": "INDEX",
      "unit": "Index (1982-84=100)",
      "frequency": "MONTHLY",
      "createdAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "hasMore": true,
    "nextCursor": "eyJpZCI6ImNzZXJfMDF..."
  }
}

GET/api/v1/series/:seriesId/values

Get time series data points for a specific index. Returns values in ascending date order. Use the from and to parameters to scope a date range, and version to filter by data revision status.

Parameters

Parameter	Type	Required	Description
`seriesId`	string (UUID)	Yes	The series UUID.
`from`	string (YYYY-MM-DD)	No	Start date, inclusive.
`to`	string (YYYY-MM-DD)	No	End date, inclusive.
`limit`	integer	No	Max data points to return. Default: 500. Max: 2000.
`version`	string	No	Filter by version tag: PRELIMINARY, FINAL, or REVISED.

Example Request

curl "https://cpam.app/api/v1/series/cser_01jz.../values?from=2025-01-01&to=2025-12-31&version=FINAL" \
  -H "Authorization: Bearer cpam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "series": {
    "id": "cser_01jz...",
    "seriesCode": "CUUR0000SA0",
    "name": "CPI All Urban Consumers",
    "unit": "Index (1982-84=100)",
    "frequency": "MONTHLY"
  },
  "data": [
    {
      "asOfDate": "2025-01-01T00:00:00.000Z",
      "value": "314.175",
      "versionTag": "FINAL"
    },
    {
      "asOfDate": "2025-02-01T00:00:00.000Z",
      "value": "315.493",
      "versionTag": "FINAL"
    }
  ],
  "total": 12
}

GET/api/v1/pams

List price adjustment formulas (PAMs) in your workspace. Returns summary objects — use /api/v1/pams/:pamId for full formula detail including adjustment frequency and contract dates.

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Results per page. Default: 50. Max: 200.
`cursor`	string	No	Pagination cursor from a previous response.

Example Request

curl https://cpam.app/api/v1/pams \
  -H "Authorization: Bearer cpam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "id": "pam_01jz...",
      "name": "Steel Supply Agreement — CPI + PPI Blend",
      "description": "60% CPI All Items, 40% PPI Metals",
      "status": "ACTIVE",
      "createdAt": "2026-01-10T08:00:00.000Z",
      "updatedAt": "2026-04-01T14:22:00.000Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

GET/api/v1/pams/:pamId

Get the full detail for a single price adjustment formula, including contract date range and adjustment frequency.

Parameters

Parameter	Type	Required	Description
`pamId`	string (UUID)	Yes	The formula UUID.

Example Request

curl https://cpam.app/api/v1/pams/pam_01jz... \
  -H "Authorization: Bearer cpam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": {
    "id": "pam_01jz...",
    "name": "Steel Supply Agreement — CPI + PPI Blend",
    "description": "60% CPI All Items, 40% PPI Metals",
    "status": "ACTIVE",
    "contractStartDate": "2025-01-01T00:00:00.000Z",
    "contractEndDate": "2027-12-31T00:00:00.000Z",
    "adjustmentFrequency": "ANNUAL",
    "createdAt": "2026-01-10T08:00:00.000Z",
    "updatedAt": "2026-04-01T14:22:00.000Z"
  }
}

GET/api/v1/pams/:pamId/values

Get computed price adjustment values for a formula. Each entry includes the adjustment percentage for that period and the running cumulative adjustment since the contract start date.

Parameters

Parameter	Type	Required	Description
`pamId`	string (UUID)	Yes	The formula UUID.
`from`	string (YYYY-MM-DD)	No	Start date, inclusive.
`to`	string (YYYY-MM-DD)	No	End date, inclusive.

Example Request

curl "https://cpam.app/api/v1/pams/pam_01jz.../values?from=2025-01-01&to=2026-01-01" \
  -H "Authorization: Bearer cpam_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "data": [
    {
      "adjustmentDate": "2026-01-01T00:00:00.000Z",
      "adjustmentPct": "3.42",
      "cumulativePct": "3.42"
    }
  ]
}

Error Responses

All errors return a JSON object with a single error field containing a human-readable message:

{ "error": "Human-readable error message" }

Status	Meaning
`200 OK`	Request succeeded.
`400 Bad Request`	Invalid query parameters or request body.
`401 Unauthorized`	Missing, invalid, or expired API key.
`404 Not Found`	The requested resource does not exist or is not accessible to your workspace.
`429 Too Many Requests`	Rate limit exceeded. Check the `Retry-After` header for the wait time in seconds.
`500 Internal Server Error`	An unexpected error occurred on our end. Retry with exponential backoff; if the issue persists, contact support.

Support

Need help? Email api@cpam.app or open an issue on GitHub.