API Reference

The current Souma application exposes a small proxy layer for RtU validation. These routes sit in front of the upstream validation service and are the API surface reflected by the dashboard and docs.

Base origin

http://localhost:3000

In production, use your deployed Souma app origin instead of localhost.

Authentication

Authenticate requests with a Souma API key:

Authorization: Bearer YOUR_API_KEY

Endpoints

POST /api/validate

Submit one or more RtU validations.

Request body:

Example request:

curl -X POST http://localhost:3000/api/validate \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "validations": [
      {
        "request_id": "job-001",
        "url": "https://example.com/article",
        "purpose": "customer-facing publication"
      }
    ]
  }'

Example response:

{
  "results": [
    {
      "request_id": "job-001",
      "validation_id": "val_abc123",
      "status": "COMPLETED",
      "url": "https://example.com/article",
      "usage_purpose": "customer-facing publication",
      "allowed_for_use": "PERMITTED",
      "confidence_score": 0.92,
      "llm_reasoning": "The site policy permits this use with attribution.",
      "conditions": ["Retain attribution"],
      "policy_source_urls": ["https://example.com/terms"],
      "error_message": null,
      "error_type": null,
      "created_at": "2026-04-25T10:15:00Z",
      "completed_at": "2026-04-25T10:15:03Z"
    }
  ]
}

GET /api/validate/result/:id

Poll a single validation by validation_id.

GET /api/validate/results

List existing results with pagination.

GET /api/validate/stream

Stream validation results for long-running checks.

GET /api/stats

Retrieve account-level statistics for the homepage and Pulse.

Timeouts

The current proxy uses hard timeouts:

Long-running workloads should use smaller batches plus polling or SSE instead of one blocking submission.

Error codes

Result statuses and judgments