Skip to main content

Using the API with AI agents

Coding assistants and AI agents integrate fastest when they are handed the API's contract up front instead of guessing it. Three resources exist for exactly that:

  • llms.txt: a compact, plain-text summary of the API at a stable URL, following the llms.txt convention.
  • The OpenAPI 3.1 specification: the complete machine-readable contract; agents can read it directly or you can load it into a tool.
  • The onboarding prompt below: paste it into your assistant at the start of an integration task.

Onboarding prompt​

You are integrating with the eCourtDate Document Generation API.

Facts:
- Base URL: https://api.pdfs.ecourtdate.com/v1
- Auth: every request sends the API key in the `x-api-key` header. Keys are
  created in the eCourtDate Console (https://console.ecourtdate.com/apis) and
  carry scopes: templates:read, templates:write, generate, audit:read.
- Write operations also require an `X-On-Behalf-Of` header (email or user id
  of the person the call is made for); it is recorded in the audit trail.
- OpenAPI 3.1 spec: https://docs.pdfs.ecourtdate.com/openapi.yaml. Treat it
  as the source of truth for every path, schema, and example.
- Docs: https://docs.pdfs.ecourtdate.com

Core model:
- Templates hold immutable, numbered versions (draft → ready → published →
  superseded). Generation renders the published version unless the request
  pins `version`. Publishing is the only way production output changes.
- Versions declare typed merge_tags; POST /v1/templates/{id}/generate renders
  with `data` validated strictly by default (422 MISSING_MERGE_TAGS /
  INVALID_MERGE_VALUES / UNKNOWN_MERGE_TAGS). `dry_run: true` validates
  without rendering.
- POST /v1/documents renders one-off documents: blank pages (`page`) with
  absolutely positioned `fields`, or whole documents authored in HTML/CSS
  (`html.content`; requires `response.mode: "json"`).
- Field types: text (plain or markdown), field, checkbox, symbol, fill,
  image, barcode, table, html. Coordinates are PDF points, top-left origin,
  Y down.
- Batch: POST /v1/templates/{id}/generate-batch (≤200 items) then poll
  GET /v1/jobs/{jobId}; download URLs are re-signed on every read.

Conventions:
- snake_case fields; cursor pagination (`limit`, `cursor` → `next_cursor`).
- Errors are RFC 9457 application/problem+json with a stable `error_code`
  and a `request_id`. Branch on `error_code`; treat the set as open.
- Rendering warnings never fail a document; they arrive in `warnings` (JSON)
  or the `X-Warnings` header (binary). `on_warning: "error"` makes them fail.
- Send an `Idempotency-Key` on every POST; retries with the same key replay
  the original result (`Idempotent-Replay: true`) and can never duplicate a
  generated document. Same key + different body → 409.
- Generated outputs expire ~20 hours after creation; download URLs last
  1 hour and are re-signed via GET /v1/outputs/{outputId}. Download files
  promptly; the API is not a document store.

Rules:
- Never hardcode an API key; read it from configuration.
- Do not invent endpoints or fields: everything is in the OpenAPI spec.
- Validate request bodies against the spec; the API rejects unknown fields
  (400 UNKNOWN_FIELD).

Practices for agent-driven integrations​

  • Give the agent the spec, not screenshots. The spec carries every schema constraint (lengths, enums, defaults) that prose summaries drop.
  • Keep the key out of the loop. Provide the key via environment or configuration the agent doesn't print; agents should write code that reads it, never embed it.
  • Have agents use idempotency keys. Agent-written retry loops are exactly where duplicate-document bugs come from.
  • Test against dry_run first. An agent can validate its data mapping end-to-end (dry runs) before rendering anything.
  • Generated clients are another option: the spec is standard OpenAPI 3.1, so any client generator your stack prefers will work.