Requests and Responses

Base URL, identifiers and dates, access rules, rate limits, errors, and versioning.

​

Base URL

All API requests are made over HTTPS to the following base URL. Responses are always JSON encoded as UTF-8:

https://app.policymate.io/api/v0

​

Identifiers and Dates

Every record has a stable id, which is a UUID. Bills also include their official number when the source publishes one.

Calendar dates, such as the date a bill was introduced, are formatted as YYYY-MM-DD. Timestamps are ISO 8601 strings in UTC, such as 2026-11-04T15:22:10Z.

​

Access

The API only returns records your subscription covers, along with the workspaces chosen for your API key. Requesting a record outside of your access returns a 404 response, exactly as if the record did not exist.

​

Rate Limiting

Each API key may make up to 120 requests per minute. Every response includes headers describing your current rate limit status:

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

When the limit is exceeded, the API returns a 429 response with a Retry-After header. The header contains the number of seconds you should wait before trying again.

​

Errors

The API uses conventional HTTP status codes to indicate whether a request succeeded:

Status	Meaning
200	The request succeeded
401	The API key is missing, rotated, or revoked
403	Your organisation’s subscription is not active
404	The record does not exist, or is outside of your access
422	The request contains invalid parameters
429	You have exceeded the rate limit

​

Validation Errors

When a request contains invalid parameters, the API returns a 422 response. The response body contains a message, along with an errors object listing each invalid parameter and its error messages:

{
  "message": "The selected jurisdiction is invalid.",
  "errors": {
    "jurisdiction": ["The selected jurisdiction is invalid."]
  }
}

​

Versioning

The API version is part of the URL. While the API is in beta, it is served at /api/v0, and its schema may still change. From v1 onward, we only add fields to a version and never remove or rename them. Breaking changes are released as a new version, announced at least six months in advance.