API Explorer

Internal reference for request/response contracts. Keep this page updated as endpoints evolve.

Authentication

All business endpoints require authentication via Clerk bearer token.
For local debugging only, AUTH_BYPASS=true can be enabled with dev headers.

Org Scoping

Write/read DB operations must include explicit organization_id filtering in queries/RPC logic.
RLS remains enabled by organization_id and acts as the hard guardrail.
Controllers pass auth.organizationId downstream; clients must not send org id in request payloads.

Endpoints

POST /api/entries/update-draft

Updates draft entry fields. Returns 200 OK.

Only draft entries can be patched.

{
  "entryId": "347ba86a-5716-4d6d-95af-298995661152",
  "reportingDate": "2026-03-31",
  "transactionTypeId": "feae48bc-9a62-4b43-9e60-bb8bc181daf3",
  "subEntries": [
    {
      "subEntryTypeId": "3cf4f3e3-115f-44c8-a49a-de9977a8336c",
      "baseAmount": 1500,
      "localAmount": 1500
    }
  ]
}

POST /api/entries/create-draft

Creates a draft entry (does not book). Returns 201 Created.

Required fields: dealId, projectId, entryTypeId, allocationRuleId, effectiveDate, reportingDate.

{
  "dealId": "9dbfb820-ee2f-4f50-a4a0-5c300b92e67c",
  "projectId": "496d37b9-4d65-46e9-a09e-2c8b0f0c4700",
  "entryTypeId": "7e12ae10-2f87-4d92-8218-4a1f3f707163",
  "allocationRuleId": "f19dc8ee-798b-4298-944a-32293ff4997e",
  "effectiveDate": "2026-02-28",
  "reportingDate": "2026-02-28",
  "transactionTypeId": "feae48bc-9a62-4b43-9e60-bb8bc181daf3",
  "isForecast": false,
  "subEntries": [
    {
      "subEntryTypeId": "3cf4f3e3-115f-44c8-a49a-de9977a8336c",
      "baseAmount": 1000,
      "localAmount": 1000
    }
  ]
}

POST /api/entries/create-and-book

Creates an entry, writes sub-entries, and books transactionally. Returns 201 Created.

Required fields: dealId, projectId, entryTypeId, allocationRuleId, effectiveDate, reportingDate.

Recommended: provide transactionTypeId (server maps code into transaction_type).

{
  "dealId": "9dbfb820-ee2f-4f50-a4a0-5c300b92e67c",
  "projectId": "496d37b9-4d65-46e9-a09e-2c8b0f0c4700",
  "entryTypeId": "7e12ae10-2f87-4d92-8218-4a1f3f707163",
  "allocationRuleId": "f19dc8ee-798b-4298-944a-32293ff4997e",
  "effectiveDate": "2026-02-28",
  "reportingDate": "2026-02-28",
  "transactionTypeId": "feae48bc-9a62-4b43-9e60-bb8bc181daf3",
  "isForecast": false,
  "subEntries": [
    {
      "subEntryTypeId": "3cf4f3e3-115f-44c8-a49a-de9977a8336c",
      "baseAmount": 1000,
      "localAmount": 1000
    }
  ]
}

POST /api/entries/revise-booked

Revises an existing booked entry by creating a replacement booked entry and superseding the source entry. Returns 201 Created.

Required fields: sourceEntryId, projectId, entryTypeId, allocationRuleId, effectiveDate, reportingDate.

{
  "sourceEntryId": "347ba86a-5716-4d6d-95af-298995661152",
  "projectId": "496d37b9-4d65-46e9-a09e-2c8b0f0c4700",
  "entryTypeId": "7e12ae10-2f87-4d92-8218-4a1f3f707163",
  "allocationRuleId": "f19dc8ee-798b-4298-944a-32293ff4997e",
  "effectiveDate": "2026-03-31",
  "reportingDate": "2026-03-31",
  "transactionTypeId": "feae48bc-9a62-4b43-9e60-bb8bc181daf3",
  "isForecast": false,
  "subEntries": [
    {
      "subEntryTypeId": "3cf4f3e3-115f-44c8-a49a-de9977a8336c",
      "baseAmount": 1200,
      "localAmount": 1200
    }
  ]
}

POST /api/entries/book

Books an existing draft entry. Returns 200 OK.

{
  "entryId": "347ba86a-5716-4d6d-95af-298995661152",
  "expectedEntryTypeId": "7e12ae10-2f87-4d92-8218-4a1f3f707163",
  "effectiveDate": "2026-02-28",
  "reportingDate": "2026-02-28"
}

POST /api/entries/validate-roc

Validates ROC amount for a deal without booking. Returns 200 OK.

{
  "dealId": "9dbfb820-ee2f-4f50-a4a0-5c300b92e67c",
  "rocBaseAmount": 500
}

POST /api/allocation-rules/validate

Validates allocation split payloads. Returns 200 OK.

{
  "fundSplits": [
    { "fundFamilyId": "fund_1", "percentage": 60 },
    { "fundFamilyId": "fund_2", "percentage": 40 }
  ],
  "legalEntitySplits": [
    { "fundFamilyId": "fund_1", "legalEntityId": "le_1", "percentage": 60 },
    { "fundFamilyId": "fund_2", "legalEntityId": "le_2", "percentage": 40 }
  ]
}

Error Contract

Success envelope:

{ "success": true, "data": { ... } }

Error envelope:

{ "success": false, "error": "Message", "code": "DOMAIN_CODE", "details": { ... } }

Common Domain Error Codes

PROJECT_REQUIRED (422)
PROJECT_NOT_FOUND (404)
ALLOCATION_RULE_REQUIRED (422)
ALLOCATION_RULE_NOT_FOUND (404)
TRANSACTION_TYPE_NOT_FOUND (404)
TRANSACTION_TYPE_REQUIRED_FOR_BOOKING (422)
INVALID_SUB_ENTRY_PAYLOAD (422)
ROC_EXCEEDS_REMAINING_INVESTED (422)