Capturia / docs
FR

Changelog

History of changes to the Capturia API v1, dated and categorized.

  1. Changedv1

    GET /v1/conversations/{id}/messages: content no longer carries internal agent control markers

    AI agents pace their replies with internal markers ([PAUSE:3s] to send in several bubbles, [INPUT:email] to request a field from the visitor). They were never part of the contract, yet they surfaced in the content field. They are now stripped: a reply the agent sent as several bubbles reaches you as paragraphs separated by a blank line. This applies to messages already stored, so the value of content changes once for existing agent messages. Worth knowing: a message that carried ONLY control markers becomes an empty string. The row stays in the page, with its id, role and created_at, so that total_count, has_more and the pagination cursor stay accurate. If your integration checks for a message with if (!content), switch it to checking that the object is present.

  2. Addedv1

    Dedicated api.capturia.io subdomain + legacy host sunset 2027-05-03

    The public API is now served at https://api.capturia.io/v1/* (enterprise convention aligned with Stripe/Twilio/GitHub). OpenAPI bundle auto-discoverable at api.capturia.io/openapi.{yaml,json}. The legacy host app.capturia.io/api/v1/* remains active until 2027-05-03; every legacy response carries IETF Deprecation, Sunset and Link successor-version headers. At sunset, the legacy host switches to HTTP 308 Permanent Redirect to the new host. No 410 Gone — your integrations will keep working even if you forget to migrate (with one round-trip of overhead).

  3. Addedv1

    OpenAPI 3.1 public spec + Postman + TS types

    The API now exposes an OpenAPI 3.1 spec at /openapi.yaml (235KB) and /openapi.json (289KB). Postman collection (/postman-collection.json) downloadable, importable in Insomnia 2023+ via the OpenAPI spec directly. TypeScript types generated at build (lib/api/v1/openapi-types.ts). Request validation against spec in shadow mode by default.

  4. Addedv1

    GET /v1/usage endpoint + observability headers

    Programmatic /v1/usage endpoint returns consumption aggregations (filterable by bucket_type and range). Every response now emits X-Request-ID ULID, Capturia-Request-ID (alias), Capturia-Version: v1, and Vary: Accept-Language, Accept-Encoding.

  5. Addedv1

    Opaque cursor pagination + Deprecation/Sunset legacy headers

    All GET collection endpoints now accept ?cursor= opaque base64url with id tiebreaker for stable sort. Legacy total_count + cursor ISO format accepted alongside for 12 months (sunset 2027-05-03). Deprecation (RFC 9745) + Sunset (RFC 8594) + Link rel=deprecation headers announce the removal.

  6. Addedv1

    Idempotency-Key header on POST/PUT/DELETE

    All mutating routes accept an optional Idempotency-Key header (regex [a-zA-Z0-9_-]{1,64}). TTL 24h via Vercel KV. Verbatim replay returns Idempotent-Replayed: true. Conflict (different payload or concurrent request) → 409 idempotency_conflict.

  7. Addedv1

    RFC 9331 headers + enriched 429 body

    Parallel emission of RateLimit-Limit/Remaining/Reset/Policy headers (RFC 9331) and X-RateLimit-* (legacy, sunset 2027-05-03). 429 body now includes actionable details.limit_type (per_key or brute_force) and details.retry_after_seconds.