{
  "service": "b12-contacts-api",
  "version": "0.1.0",
  "auth": "Authorization: Bearer <API_TOKEN> on every route except / and /_routes",
  "modes": {
    "read": "GET and OPTIONS only (default)",
    "write": "adds create, update, upsert",
    "full": "adds delete, bulk-delete, CSV/email import"
  },
  "notes": [
    "Destructive routes also require ?confirm=yes.",
    "Unknown query parameters are forwarded to B12 verbatim; filter_by and order_by are known to work, the rest of their vocabulary is unverified.",
    "Prefer /contacts/export.csv over /contacts/all for a full dump: one request instead of ~254."
  ],
  "routes": [
    [
      "GET",
      "/_selfcheck",
      "runtime + secrets readiness, makes no call to b12.io"
    ],
    [
      "GET",
      "/health",
      "session + mode diagnostics, no B12 call for contacts"
    ],
    [
      "POST",
      "/session/refresh",
      "force a fresh b12.io login"
    ],
    [
      "POST",
      "/session/reset",
      "discard the stored session"
    ],
    [
      "GET",
      "/contacts",
      "one page; passthrough params: page, order_by, filter_by, ..."
    ],
    [
      "GET",
      "/contacts/all",
      "walk pages; ?maxPages=10&page=1, returns next_page cursor"
    ],
    [
      "GET",
      "/contacts/export.csv",
      "full CSV export in a single request"
    ],
    [
      "GET",
      "/contacts/schema",
      "DRF OPTIONS metadata: the authoritative field list"
    ],
    [
      "GET",
      "/contacts/tags",
      "tag lists (filtered_contacts, all_contacts)"
    ],
    [
      "GET",
      "/contacts/:id",
      "one contact"
    ],
    [
      "POST",
      "/contacts",
      "create  [write]"
    ],
    [
      "PATCH|PUT",
      "/contacts/:id",
      "update  [write]"
    ],
    [
      "POST",
      "/contacts/upsert",
      "create_or_update - use this for syncing  [write]"
    ],
    [
      "DELETE",
      "/contacts/:id",
      "delete  [full] ?confirm=yes"
    ],
    [
      "POST",
      "/contacts/bulk-delete",
      "delete many  [full] ?confirm=yes"
    ],
    [
      "POST",
      "/contacts/import/csv",
      "CSV import, body forwarded raw  [full] ?confirm=yes"
    ],
    [
      "POST",
      "/contacts/import/email",
      "import from a connected mailbox  [full] ?confirm=yes"
    ],
    [
      "GET",
      "/forms",
      "contact forms"
    ],
    [
      "GET",
      "/forms/:formId",
      "one contact form"
    ],
    [
      "GET",
      "/forms/:formId/submissions",
      "form submissions"
    ],
    [
      "GET",
      "/forms/:formId/submissions/:pk",
      "one submission"
    ],
    [
      "POST",
      "/forms/:formId/submissions/mark-seen",
      "mark submissions seen  [write]"
    ],
    [
      "ANY",
      "/raw?path=/contact/...",
      "escape hatch onto any b12.io path"
    ]
  ]
}