Getting started

Lumen extracts checkable facts from PDF documents, grounds every claim to its exact source page, and reasons about relationships — detecting which facts corroborate, contradict, or reconcile across your uploads.

The REST API is completely open at https://lumen-obli.onrender.com. No authentication keys or signup are required to upload files or query the reasoning graph.

Protocol & conventions

All upload requests must be sent as multipart/form-data with the file included under the file parameter. Responses are returned as standard UTF-8 JSON.

Documents with 2 pages or fewer are processed synchronously and return extracted facts immediately. Larger documents return 202 Accepted and process in the background; you can poll the status endpoint until complete.

Upload a document

POST/v1/documents

Uploads a PDF for chunking, text & OCR extraction, entity-attribute-value fact extraction, and cross-document relationship reasoning.

bash

curl -X POST https://lumen-obli.onrender.com/v1/documents \
  -F "file=@/path/to/document.pdf"

json

{
  "document_id": "a1b2c3d4-...",
  "facts": [
    {
      "id": "f8a9b0c1-...",
      "entity": "Delhivery Limited",
      "attribute": "Total Revenue FY24",
      "value": "8,142",
      "unit": "INR Crore",
      "quote": "Revenue from operations reached ₹8,142 Cr for the fiscal year ended March 31, 2024.",
      "confidence": 0.96
    }
  ],
  "relationships": [
    {
      "id": "r1a2b3c4-...",
      "factAId": "f8a9b0c1-...",
      "factBId": "f2b3c4d5-...",
      "relationType": "corroborates",
      "explanation": "Consistent with earnings report filed in Q4 investor deck.",
      "confidence": 0.95
    }
  ]
}

Document status

GET/v1/documents/:id/status

Poll this endpoint while a document is processing. Status transitions from processing to done or error.

bash

curl https://lumen-obli.onrender.com/v1/documents/a1b2c3d4-.../status

json

{
  "status": "processing",
  "pages_processed": 3,
  "pages_total": 10,
  "error": null
}

List facts

GET/v1/documents/:id/facts

Returns paginated facts extracted from the document along with cross-document relationship counts.

Param	Default	Notes
limit	100	Max 500
offset	0	Pagination offset
q	—	Free-text search across entity, attribute, value
filter	—	corroborates, contradicts, or reconciled

bash

curl "https://lumen-obli.onrender.com/v1/documents/a1b2c3d4-.../facts?limit=20&filter=contradicts"

json

{
  "facts": [
    {
      "id": "f8a9b0c1-...",
      "entity": "Delhivery",
      "attribute": "Adjusted EBITDA",
      "value": "127",
      "unit": "INR Crore",
      "quote": "Adjusted EBITDA turned positive to ₹127 Cr compared to a loss in previous period.",
      "confidence": 0.92
    }
  ],
  "total": 143,
  "limit": 20,
  "offset": 0,
  "relationshipCount": 12,
  "relationSummary": {
    "f8a9b0c1-...": {
      "contradicts": 1
    }
  }
}

Single fact & relationships

GET/v1/facts/:id

Retrieves an individual fact with its verbatim quote, source chunk text, page number, and any corroborating or contradictory relationships with other facts.

bash

curl https://lumen-obli.onrender.com/v1/facts/f1e2d3c4-...

json

{
  "fact": {
    "id": "f1e2d3c4-...",
    "entity": "Delhivery",
    "attribute": "Express Parcel Volume",
    "value": "740",
    "unit": "Million orders",
    "quote": "Handled over 740 million express parcel shipments across India."
  },
  "source": {
    "pageNumber": 4,
    "chunkText": "During the year under review, express parcel shipment volumes crossed 740 million orders."
  },
  "relationships": [
    {
      "id": "rel-9921",
      "relationType": "contradicts",
      "explanation": "Earlier prospectus cited 705 million shipments for the overlapping period.",
      "relatedFact": {
        "id": "fact-prev",
        "entity": "Delhivery",
        "attribute": "Express Parcel Volume",
        "value": "705",
        "unit": "Million orders"
      }
    }
  ]
}

Original PDF

GET/v1/documents/:id/file

Streams the raw uploaded PDF binary with Content-Type: application/pdf. Suitable for embedding in an <iframe> or passing to PDF.js.

bash

curl -O https://lumen-obli.onrender.com/v1/documents/a1b2c3d4-.../file

Errors

All endpoints return an error JSON object with an HTTP 4xx or 5xx status code on failure — 404 for unknown document or fact IDs, 400 for a missing upload file, and 500 for unexpected server errors.

json

{
  "error": "Document not found"
}