rest_api_contract.md

REST API Contract (C1 · Transactional Channel)

This document defines the HTTP API surface that anchors:

• P1 · Session Lifecycle (session creation and lookup)
• P5 · Billing & Entitlement (checkout and payment notification)

It is MVP-faithful:

• All endpoints and fields exist in the running MVP backend
• No additional capabilities are introduced beyond current behavior

---

TL;DR (60-second read)

• Base path: /api
• Minimal endpoint set:
  • POST /api/session – create analysis session (returns sessionId)
  • GET /api/session/:sessionId – inspect session and obtain resultKey
  • POST /api/checkout – create a checkout session for a topic
  • POST /api/webhook – payment provider webhook (server-to-server only)
• This channel never delivers analysis content; all content flows via C1 stream.

---

1. Scope & Non-Goals

Scope

• Session creation and minimal inspection
• Payment initiation via an external checkout session
• Payment completion notification via a payment provider webhook

Non-Goals

• User account management or authentication
• Analysis execution or result delivery
• Generic billing abstraction beyond the current payment provider integration
• Multi-tenant or multi-project routing

---

2. Endpoint Overview

Method	Path	Role
POST	/api/session	Create analysis session
GET	/api/session/:sessionId	Inspect session, get resultKey
POST	/api/checkout	Create payment provider checkout session
POST	/api/webhook	Payment provider webhook endpoint

---

3. POST /api/session

Create an ephemeral analysis session and register canonical analysis input.

Request

Content-Type: application/json

{
  "input": {
    "...": "domain-specific analysis input (omitted in this contract)"
  }
}

• Request body MUST be a JSON object.
• Field-level schema is domain-specific and intentionally omitted here.
• The backend treats this payload as the canonical input bound to the session.

Responses

Success

{
  "code": 200,
  "data": {
    "sessionId": "uuid-value",
    "message": "session created"
  }
}

Validation error

HTTP 400:

{
  "code": 400,
  "message": "invalid or incomplete input"
}

Validation messages are implementation-specific; only the shape is normative.

Server error

HTTP 500:

{
  "code": 500,
  "message": "internal server error"
}

---

4. GET /api/session/:sessionId

Inspect an existing session and obtain identifiers needed by the streaming layer.

Request

Path parameter:

• sessionId – UUID returned by POST /api/session

Responses

Success

{
  "code": 200,
  "data": {
    "sessionId": "uuid-value",
    "resultKey": "opaque_key",
    "status": "pending",
    "progress": 0,
    "paid": false,
    "createdAt": 1710000000000,
    "topics": []
  }
}

Fields other than sessionId and resultKey are implementation details and may evolve.

Not found

HTTP 404:

{
  "code": 404,
  "message": "session not found or expired"
}

---

5. POST /api/checkout

Initiate a payment provider checkout session for a given session and topic.

Request

Content-Type: application/json

{
  "sessionId": "uuid-value",
  "topic": "topicA"
}

• sessionId (string, required) – existing session identifier
• topic (string, required) – analysis topic label

Responses

Success

{
  "code": 200,
  "message": "checkout session created",
  "data": {
    "checkoutUrl": "https://checkout.example.com/...",
    "providerSessionId": "opaque-session-id"
  }
}

Validation or existence error

HTTP 400 or 404:

{
  "code": 400,
  "message": "sessionId and topic are required"
}

or:

{
  "code": 404,
  "message": "session not found or expired"
}

Server error

HTTP 500:

{
  "code": 500,
  "message": "failed to create checkout session"
}

---

6. POST /api/webhook

Payment provider webhook endpoint. This is not called by clients; it is invoked by the payment provider.

Behavior

• Expects a provider-specific signature header and raw JSON body
• Verifies signature using the configured webhook secret
• On a successful checkout completion event:
  • Extracts sessionId and topic from event.data.object.metadata
  • Marks the corresponding topic as paid in the in-memory session store
  • Marks payment notification status for that topic as pending
  • Attempts a best-effort push to any still-open WebSocket client via notifyPaymentSuccess(sessionId, topic); if no client is connected, only the stored payment state is updated

Response shape:

{
  "received": true
}

On signature failure, the endpoint returns HTTP 400 with a plain-text error message.

---

Health endpoints are intentionally out of scope for this contract.