> ## Documentation Index
> Fetch the complete documentation index at: https://docs.policymate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```text theme={null}
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:

```http theme={null}
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:

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.