Documentation / API overview

Index

Digitize an archive and make every page searchable.

What you get

Index reads a set of documents into a named collection. Scans and image-only PDFs are digitized first, so pages that hold no text layer become searchable text. Each indexed page keeps its source document and page number, so every later result can cite where it came from.

A collection is queried in two ways. Search returns the pages that match a query. Ask returns a written answer over the collection with the passages it relied on.

When to use Index

• Make a back catalogue of scanned leases, policies, or contracts searchable.
• Find every page that mentions a clause, a party, or a date across an archive.
• Answer questions over a document set and show the source pages for each answer.

Index a collection

Proposed API contract

Send the documents to index and the collection they belong to. A collection can be indexed more than once; new documents are added to it.

curl https://api.moda.app/v1/documents/index \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection": "leases_1998",
  "file_refs": [
    "file_lease_0001",
    "file_lease_0002"
  ]
}'

The request starts a job. Poll the returned poll_url until the status is completed or failed. See the shared job lifecycle.

{
  "id": "job_index_example",
  "status": "completed",
  "result": {
    "collection": "leases_1998",
    "documents_indexed": 2,
    "pages_indexed": 47,
    "pages_digitized": 47,
    "warnings": []
  }
}

Search a collection

Search runs against an indexed collection and returns matching pages in relevance order. It responds directly rather than starting a job.

curl https://api.moda.app/v1/documents/index/search \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection": "leases_1998",
  "query": "termination clause",
  "limit": 2
}'

{
  "collection": "leases_1998",
  "hits": [
    {
      "file_ref": "file_lease_0002",
      "page": 11,
      "score": 0.92,
      "snippet": "Either party may terminate this lease upon ninety days written notice."
    },
    {
      "file_ref": "file_lease_0001",
      "page": 8,
      "score": 0.81,
      "snippet": "Termination for cause is governed by Section 14."
    }
  ]
}

Ask a question

Ask answers a question over the collection and returns the passages the answer rests on. Every citation names a document and a page, so an answer can be checked against its source.

curl https://api.moda.app/v1/documents/index/ask \
  -H "Authorization: Bearer $MODA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "collection": "leases_1998",
  "question": "How much notice is required to terminate?"
}'

{
  "collection": "leases_1998",
  "answer": "Ninety days written notice, from either party.",
  "citations": [
    {
      "file_ref": "file_lease_0002",
      "page": 11,
      "quote": "Either party may terminate this lease upon ninety days written notice."
    }
  ]
}

Fields

collection

The collection to index into, search, or ask. Names it yourself.

file_refs

The uploaded documents to add to the collection.

result.pages_digitized

Pages that carried no text layer and were read as images.

hits[]

Matching pages with their source document, page number, and matched text.

citations[]

The passages an answer is drawn from.

result.warnings

Pages that could not be read or need review.

Example workflow

1. Upload a back catalogue of scanned leases.
2. Index them into a collection.
3. Search the collection from your application, or ask questions over it and show each answer’s cited pages.

Index or Parse?

Choose Index when the archive itself is the unit of work and you need to search or question it. Choose Parse when you need one document’s full representation, or Extract when you know which fields you want from a known set of files.