# eCourtDate Electronic Warrants API Documentation

> The canonical reference for the eCourtDate Electronic Warrants API
> (https://api.warrants.ecourtdate.com/v1). Draft warrant applications from
> templates, submit them for review, route them to a judge, sign or reject
> them, and read the resulting records and audit trail.

## Key resources

- [API reference (interactive)](https://docs.warrants.ecourtdate.com/reference/)
- [OpenAPI 3.1 specification](https://docs.warrants.ecourtdate.com/openapi.json)
- [Guides index](https://docs.warrants.ecourtdate.com/guides)
- [Getting started](https://docs.warrants.ecourtdate.com/guides/getting-started)
- [Authentication](https://docs.warrants.ecourtdate.com/guides/authentication)
- [Warrant lifecycle](https://docs.warrants.ecourtdate.com/guides/warrant-lifecycle)
- [Form elements](https://docs.warrants.ecourtdate.com/guides/form-elements)
- [Errors](https://docs.warrants.ecourtdate.com/guides/errors)
- [Using the API with AI agents](https://docs.warrants.ecourtdate.com/guides/ai-agents)

## Facts

- Base URL: https://api.warrants.ecourtdate.com/v1
- Authentication: API key in the `x-api-key` header on every authenticated
  request. Keys are issued and activated for one agency by eCourtDate and
  carry scopes: warrants:read, warrants:write, warrants:submit, warrants:sign,
  templates:read, templates:write, files:read, files:write, locations:read,
  locations:write, users:read, users:write, settings:read, settings:write,
  audit:read.
- Every write also requires `X-On-Behalf-Of`, naming the person the call is
  made for. It is recorded in the audit trail, and the named person must be an
  active member of the agency who may take the action. Missing header: 422
  missing_actor. Unknown person: 403 unknown_actor.
- Core model: a warrant application is created from a template and holds its
  values in `form_data`, keyed by the template's `fieldId` values. States are
  DRAFT, SUBMITTED, SIGNED, REJECTED. Transitions: submit (creator only),
  sign, reject, reopen (REJECTED back to DRAFT). SIGNED is terminal and a
  warrant can be signed only once.
- Priority is LOW, STANDARD, or URGENT. Visibility is PUBLIC or PRIVATE; a
  PUBLIC application is readable through an unauthenticated link by slug.
- Assignment to a judge is a routing hint, not a lock: any judge in the agency
  can still sign. Unactioned assignments escalate to the whole bench on an
  agency-configured interval.
- Updates replace `form_data` wholesale. Read, modify, write back. Claim the
  advisory edit lock (POST /warrants/{id}/lock) first when a person may be
  editing the same application; a fresh lock held by someone else returns 409
  lock_held.
- Attachments: POST /files/presign, PUT the bytes to the returned URL, then
  POST /files/confirm. An unconfirmed upload does not appear on the
  application. Download URLs are short-lived and signed, and every download is
  audited.
- Errors: {"error": {message, type, code, param, request_id}}. Codes:
  missing_api_key, invalid_api_key, insufficient_scope,
  insufficient_permission, missing_actor, unknown_actor, not_found,
  invalid_request, validation_failed, invalid_transition, warrant_locked,
  lock_held, already_exists, rate_limit_exceeded, server_error. Branch on
  code, never on message.
- Rate limits: RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset on
  every response; 429 carries Retry-After. Retry only rate_limit_exceeded and
  server_error, with backoff and jitter.
- Conventions: identifiers are UUIDs, timestamps are RFC 3339 UTC, lists page
  with `skip` and `limit`, property names are snake_case except inside
  `form_data`, template `elements`, and agency settings. Treat every
  enumeration as open and ignore unknown response fields.
- Roles: PHYSICIAN, OFFICER, JUDGE, ADMIN, plus agency-defined custom roles
  built from the permission catalog at GET /permissions. A key's scopes and
  the attributed person's permissions must both allow an action.
- Warrant contents and signatures are encrypted at rest and every agency's
  records are isolated. Never log `form_data`; log `request_id` instead.