API Reference

The Contract-as-Code REST API allows you to programmatically manage contracts, run validation jobs, and retrieve findings.

Base URL

https://api.contract-as-code.com/v1

Regional endpoints are selected automatically based on your organisation's data residency configuration.

Authentication

All requests require a Bearer token:

Authorization: Bearer <api_key>

Generate API keys from Settings → API Keys in the application. See Authentication for details on scopes and permissions.

Rate limits

Plan	Requests per minute	Requests per day
Free Pilot	30	500
Per Contract	120	5,000
Monthly SaaS	600	50,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1705312320

Endpoints

Contracts

List contracts

GET /v1/contracts

Query parameters:

Param	Type	Description
status	string	Filter by status (extracting, review, active, expired, archived)
jurisdiction	string	Filter by jurisdiction code
limit	number	Max results (default 20, max 100)
offset	number	Pagination offset

Response:

{
  "data": [
    {
      "id": "ctr_abc123",
      "name": "CUPE Local 79 — 2024–2027",
      "status": "active",
      "jurisdiction": "CA-ON",
      "created_at": "2025-01-10T09:00:00Z",
      "expires_at": "2027-12-31T00:00:00Z",
      "rules_approved": 42,
      "rules_pending": 3,
      "rules_rejected": 7
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Upload contract

POST /v1/contracts
Content-Type: multipart/form-data

Field	Type	Required	Description
file	file	Yes	PDF file (max 50 MB)
name	string	Yes	Display name
jurisdiction	string	Yes	Jurisdiction code (e.g., CA-ON, US-CA, UK, AU)
expires_at	string	No	ISO 8601 date
tags	string[]	No	Tags for organisation

Response: 201 Created with the contract object.

Get contract

GET /v1/contracts/:id

Get rule candidates

GET /v1/contracts/:id/rules

Query parameters:

Param	Type	Description
status	string	pending, approved, rejected, flagged
family	string	Rule family (e.g., overtime, shift_premium, vacation)

Validation

Create validation job

POST /v1/validation
Content-Type: multipart/form-data

Field	Type	Required	Description
contract_ids	string[]	Yes	One or more contract IDs
file	file	Yes	CSV employee dataset
jurisdiction	string	Yes	Jurisdiction code
as_of_date	string	Yes	Pay period date (ISO 8601)

Response: 202 Accepted with the job object (status: queued).

Get validation job

GET /v1/validation/:id

Get findings

GET /v1/validation/:id/findings

Query parameters:

Param	Type	Description
severity	string	error, warning, review_needed
family	string	Rule family filter
employee_ref	string	Filter to a specific employee (hashed ref)
limit	number	Max results (default 50, max 500)
offset	number	Pagination offset

Reports

Generate report

POST /v1/reports

{
  "job_id": "job_abc123",
  "format": "pdf",
  "include_dismissed": false,
  "include_notes": true
}

Response: 202 Accepted with a report_id. The report is generated asynchronously.

Get report

GET /v1/reports/:id

When the report is ready, the response includes a download_url (signed, expires in 1 hour).

Webhooks

List webhooks

GET /v1/webhooks

Create webhook

POST /v1/webhooks

{
  "url": "https://your-system.com/webhook",
  "events": ["validation.completed", "contract.extraction_complete"]
}

Response includes the secret for signature verification.

Error responses

All errors follow a consistent format:

{
  "error": {
    "code": "validation_error",
    "message": "The 'jurisdiction' field is required.",
    "details": [
      {
        "field": "jurisdiction",
        "message": "This field is required."
      }
    ]
  }
}

Status code	Meaning
400	Bad request — invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — insufficient permissions
404	Not found
409	Conflict — resource already exists
422	Unprocessable — validation failed
429	Rate limited
500	Internal server error

SDKs

Coming soon

Official SDKs for Node.js, Python, and Go are in development. In the meantime, use any HTTP client with the REST API directly.