AI_template/docs/backend/api-design.md

Backend: API Design

---

Phase: Phase 0 (Planning)
Status: Draft — finalize in Phase 1
Owner: Backend Architect
References:

• /docs/backend/architecture.md
• /docs/backend/payment-flow.md
• /docs/backend/security.md

---

1. Principles

• REST with versioning (/api/v1), consistent envelope and errors.
• Tenant-scoped resources; role-based authorization.
• Idempotent ingestion/webhook endpoints; trace IDs for debugging.

Resource set is archetype‑specific. Endpoints below are a pipeline/classification example — adapt for chat‑first, generation, or automation products.

2. Core Resources (high-level)

• /auth — login, tenant context, token refresh.
• /tenants — tenant profile, roles, invites.
• /integrations — connect sources (OAuth2/webhooks), view health, rotate secrets, webhook endpoints.
• /records — list/filter, detail (raw + normalized + reasoning), bulk actions, reprocess.
• /rules — CRUD, enable/disable, test/preview, stats.
• /processing — trigger re-evaluation (rules → embeddings → LLM), inspect outcomes.
• /approvals — approval queue, approve/override, optional rule creation.
• /reports — dashboards/summary generation, export status/download.
• /billing — session/portal links, subscription status (webhook-driven).
• /events — read-only event log feed for downstream agents.
• /files/attachments — uploads/metadata (if exposed).

3. Payments/Billing (Provider-agnostic)

• POST /billing/session — create checkout session for subscription/plan change.
• GET /billing/status — current subscription status (webhook-driven source of truth).
• GET /billing/portal — customer portal link for payment method/plan management.
• POST /billing/webhooks/provider — verify signature; idempotent subscription updates; log billing events.

4. Ingestion/Webhooks

• Receivers for external providers (e.g., /integrations/webhooks/{provider}): verify signature, dedupe, enqueue to BullMQ; emit INGESTED with source_agent.

5. Processing & Approvals

• POST /processing/run — trigger re-evaluation for a scoped set (source/date/status).
• POST /approvals/{id}/approve — accept decision; log APPROVED.
• POST /approvals/{id}/override — override outcome; optional rule payload; log APPROVED and RULE_CREATED when applicable.

6. Events

• GET /events — read-only feed (paginated) for downstream agents/clients; filters: tenant, type, time range, source_agent.

7. Response Envelope (example)

{
  "data": { ... },
  "error": null,
  "meta": { "traceId": "..." }
}

Errors: data = null, error with code/message/context.