AI agents

Coding assistants write a lot of the integrations against this API. This page gives them what they need in one place.

Machine-readable resources

Resource	URL
Facts and links, condensed	llms.txt
OpenAPI 3.1 specification (JSON)	openapi.json
OpenAPI 3.1 specification (YAML)	openapi.yaml
Interactive reference	/reference/

The specification is the complete contract: every endpoint, field, enumeration, and error. Point a generator at it rather than hand-writing a client.

Briefing prompt

Paste this into your assistant before asking it to write code.

You are writing an integration against the eCourtDate Electronic Warrants API.

Base URL: https://api.warrants.ecourtdate.com/v1
Specification: https://docs.warrants.ecourtdate.com/openapi.json
Guides: https://docs.warrants.ecourtdate.com/guides

Authentication
- Every authenticated request sends the header: x-api-key: <key>
- Every write also sends: X-On-Behalf-Of: <email or user id of the person>
- Keys are agency-scoped and carry scopes such as warrants:read,
  warrants:write, warrants:submit, warrants:sign, templates:read, files:write,
  users:read, audit:read. A call outside the key's scopes returns 403.
- Keys are server-side secrets. Never put one in browser or mobile code.

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: DRAFT -> SUBMITTED -> SIGNED, or SUBMITTED -> REJECTED -> (reopen)
  -> DRAFT. SIGNED is terminal.
- Transitions: PATCH /warrants/{id}/submit, /sign, /reject, /reopen.
  Only the creator may submit. Signing applies the stored signature of the
  person in X-On-Behalf-Of and can happen only once.
- Priority is LOW, STANDARD, or URGENT. Visibility is PUBLIC or PRIVATE.
- Assignment to a judge is a routing hint, not a lock: any judge in the agency
  can still sign.

Rules to follow
- Read GET /templates/{id} and drive form_data from its elements. Do not
  hard-code field names.
- PUT /warrants/{id} replaces form_data wholesale. Read, modify, write back.
- Claim POST /warrants/{id}/lock before editing anything a person may also be
  editing; release it afterwards.
- Attachments use presign, PUT to the returned URL, then confirm. An
  unconfirmed upload does not exist.
- Errors are {"error": {message, type, code, param, request_id}}. Branch on
  code, never on message. Retry only rate_limit_exceeded (honour Retry-After)
  and server_error, with backoff and jitter.
- Timestamps are RFC 3339 UTC. Identifiers are UUIDs. Lists page with skip and
  limit.
- Treat every enumeration as open and ignore unknown response fields.
- Log request_id on failures. Never log form_data: it carries personal data.

Prompts that work well

• "Read the specification at the URL above, then write a client that creates an application from template X and submits it, validating form_data against the template's elements first."
• "Write a poller for the SUBMITTED queue that respects RateLimit-Remaining and backs off on 429."
• "Given this error payload, tell me which of my request fields is wrong and why."

Things assistants get wrong here

Worth stating explicitly, because these are the recurring mistakes:

• Merging form_data. Updates replace it. A merge in the client that is not a read-modify-write against the current value drops fields.
• Forgetting X-On-Behalf-Of. Every write needs it. 422 missing_actor is the result.
• Assuming signing is idempotent. It is not. A retry after a successful sign returns 409 invalid_transition, which is correct and should not be retried again.
• Polling the audit trail for changes. It is history, not a change feed.
• Treating 404 as "wrong id". It is also what another agency's resource returns.