Knowledge Base Corpus

Corpus browse, parsed artifact access, and grounded evidence search.

List indexed files for a knowledgebase

GET

https://api.providus.ai

/v1/knowledge-bases/{kbId}/index

Returns the knowledge-base-scoped file index for research agents and browse flows, including current version information, latest parse/extract jobs, and artifact links.

List indexed files for a knowledgebase › path Parameters

kbId

string · required

List indexed files for a knowledgebase › query Parameters

folder_id

string · uuid

Optional folder filter within the knowledgebase.

List indexed files for a knowledgebase › Responses

Knowledgebase file index

The index-first entry point for agents and research workflows. Prefer this over crawling file endpoints one by one.

KnowledgeBaseIndex

KnowledgeBase

IndexedFile[]

GET/v1/knowledge-bases/{kbId}/index

curl https://api.providus.ai/v1/knowledge-bases/:kbId/index \
  --header 'x-docai-org-id: <api-key>'

Example Responses

{
  "knowledge_base": {
    "id": "id",
    "org_id": "org_id",
    "name": "name",
    "description": "description",
    "metadata": {},
    "created_at": "2024-08-25T15:00:00Z",
    "updated_at": "2024-08-25T15:00:00Z"
  },
  "files": [
    {
      "file_id": "file_id",
      "filename": "filename",
      "content_type": "content_type",
      "folder_id": "folder_id",
      "folder_name": "folder_name",
      "current_version_id": "current_version_id",
      "version_number": 0,
      "storage_path": "storage_path",
      "sha256": "sha256",
      "byte_size": 0,
      "page_count": 0,
      "metadata": {},
      "created_at": "2024-08-25T15:00:00Z",
      "updated_at": "2024-08-25T15:00:00Z",
      "latest_parse_job": {
        "job_id": "job_id",
        "status": "status",
        "stage": "stage",
        "percent": 0,
        "error": "error",
        "created_at": "2024-08-25T15:00:00Z",
        "completed_at": "2024-08-25T15:00:00Z"
      },
      "latest_extract_job": {
        "job_id": "job_id",
        "status": "status",
        "stage": "stage",
        "percent": 0,
        "error": "error",
        "created_at": "2024-08-25T15:00:00Z",
        "completed_at": "2024-08-25T15:00:00Z"
      },
      "parse_artifacts": {
        "manifest_id": "manifest_id",
        "created_at": "2024-08-25T15:00:00Z",
        "links": {
          "result_md": "result_md",
          "grounding_json": "grounding_json",
          "workbook_json": "workbook_json",
          "tables_json": "tables_json",
          "pages": "pages",
          "imgs": "imgs"
        }
      },
      "extract_artifacts": {
        "manifest_id": "manifest_id",
        "created_at": "2024-08-25T15:00:00Z",
        "links": {
          "result_json": "result_json"
        }
      }
    }
  ]
}

json

application/json

Search grounding evidence elements

POST

https://api.providus.ai

/v1/knowledge-bases/{kbId}/search

Lexical Postgres FTS search over derived grounding evidence rows. Returns exact source pointers, table metadata, note references, neighbor ids, and page/sheet coordinates. Citations should point to the returned file id plus segment id.

Search grounding evidence elements › path Parameters

kbId

string · required

Search grounding evidence elements › Request Body

KnowledgeBaseSearchRequest

query

string · required

Lexical full-text query over parsed grounding evidence.

limit

integer · min: 1 · max: 80

Defaults to 30. Above 80 is rejected with 400.

file_ids

string[]

folder_id

string · uuid

years

integer[]

source_type

string · maxLength: 30

table_only

boolean

Restrict hits to table segments.

Search grounding evidence elements › Responses

Evidence search result

Lexical full-text search over grounding evidence. Cite the returned fileId plus segmentId.

EvidenceSearchResult

knowledge_base_id

string

index_version

string

status

string · enum

Enum values:

fresh

stale

EvidenceIndexSnapshot

EvidenceSearchHit[]

POST/v1/knowledge-bases/{kbId}/search

curl https://api.providus.ai/v1/knowledge-bases/:kbId/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "query": "revenue by segment 2025",
  "limit": 1,
  "file_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "folder_id": "00000000-0000-0000-0000-000000000000",
  "years": [
    1900
  ],
  "source_type": "source_type",
  "table_only": true
}'

Example Request Body

{
  "query": "revenue by segment 2025",
  "limit": 1,
  "file_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "folder_id": "00000000-0000-0000-0000-000000000000",
  "years": [
    1900
  ],
  "source_type": "source_type",
  "table_only": true
}

json

Example Responses

{
  "knowledge_base_id": "knowledge_base_id",
  "index_version": "index_version",
  "status": "fresh",
  "snapshot": {
    "index_version": "index_version",
    "knowledge_base_id": "knowledge_base_id",
    "current_root_hash": "current_root_hash",
    "snapshot_id": "snapshot_id",
    "snapshot_root_hash": "snapshot_root_hash",
    "status": "fresh",
    "indexed_file_count": 0,
    "indexed_segment_count": 0,
    "table_segment_count": 0,
    "note_ref_count": 0,
    "completed_at": "2024-08-25T15:00:00Z"
  },
  "hits": [
    {
      "id": "id",
      "docId": "docId",
      "fileId": "fileId",
      "fileVersionId": "fileVersionId",
      "artifactManifestId": "artifactManifestId",
      "segmentId": "segmentId",
      "docName": "docName",
      "title": "title",
      "markdown": "markdown",
      "score": 0,
      "sourceType": "sourceType",
      "coordinates": {
        "pageNumber": 0,
        "xmin": 0,
        "ymin": 0,
        "xmax": 0,
        "ymax": 0,
        "sourceType": "sourceType",
        "sheetIndex": 0,
        "sheetName": "sheetName",
        "startRow": 0,
        "endRow": 0,
        "startCol": 0,
        "endCol": 0,
        "rangeA1": "rangeA1"
      },
      "tableMetadata": {
        "isTable": true,
        "headers": [
          "string"
        ],
        "rowLabels": [
          "string"
        ],
        "noteRefs": [
          {
            "noteRef": "noteRef",
            "rowLabel": "rowLabel"
          }
        ]
      },
      "noteRefs": [
        "string"
      ],
      "years": [
        0
      ],
      "quarters": [
        "string"
      ],
      "neighbors": {
        "previousSegmentId": "previousSegmentId",
        "nextSegmentId": "nextSegmentId",
        "noteSegmentIds": [
          "string"
        ]
      }
    }
  ]
}

json

application/json

Fetch parse/extract artefact links

GET

https://api.providus.ai

/v1/files/{fileId}/artefacts

Fetch parse/extract artefact links › path Parameters

fileId

string · required

Fetch parse/extract artefact links › Responses

Artefacts

ArtifactList

ArtifactManifest[]

GET/v1/files/{fileId}/artefacts

curl https://api.providus.ai/v1/files/:fileId/artefacts \
  --header 'x-docai-org-id: <api-key>'

Example Responses

{
  "artifacts": [
    {
      "id": "c41d8e57-6b90-4a12-8e3f-7d05b2c9a418",
      "org_id": "org_2xKq9",
      "file_id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
      "file_version_id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "job_id": "9b2f1c84-5d31-4a6e-8f10-c2a7e4d90b13",
      "artifact_type": "parse",
      "manifest": {
        "pages": 12
      },
      "created_at": "2026-08-19T09:15:41.000Z",
      "links": {
        "result_md": "/v1/artifacts/c41d8e57-6b90-4a12-8e3f-7d05b2c9a418/result_md",
        "grounding_json": "/v1/artifacts/c41d8e57-6b90-4a12-8e3f-7d05b2c9a418/grounding_json",
        "result_json": null,
        "workbook_json": null,
        "tables_json": "/v1/artifacts/c41d8e57-6b90-4a12-8e3f-7d05b2c9a418/tables_json",
        "pages": "/v1/artifacts/c41d8e57-6b90-4a12-8e3f-7d05b2c9a418/pages",
        "imgs": "/v1/artifacts/c41d8e57-6b90-4a12-8e3f-7d05b2c9a418/imgs"
      }
    }
  ]
}

json

application/json

Download or list an artefact by generated link

GET

https://api.providus.ai

/v1/artifacts/{manifestId}/{artifactKey}

Generated artefact links use manifest ids and artefact keys, never raw filesystem paths.

Download or list an artefact by generated link › path Parameters

manifestId

string · required

artifactKey

string · required

Download or list an artefact by generated link › query Parameters

file

string

Download or list an artefact by generated link › Responses

Artefact bytes

string · binary

Read segment/map data from latest parse artifacts

GET

https://api.providus.ai

/v1/files/{fileId}/segments

Read segment/map data from latest parse artifacts › path Parameters

fileId

string · required

Read segment/map data from latest parse artifacts › Responses

File segments

Segment[]

A bare array, not an envelope.

A parsed segment. Fields beyond those listed are carried through from the parse artifact.

Segment

id

string

docId

string

docName

string

title

string

markdown

string

pdfUrl

string

xlsxUrl

string

EvidenceCoordinate

Page box for PDFs and images; sheet range for spreadsheets.

sourceType

string

Document Edit

List indexed files for a knowledgebase

GET

https://api.providus.ai

/v1/knowledge-bases/{kbId}/index

Returns the knowledge-base-scoped file index for research agents and browse flows, including current version information, latest parse/extract jobs, and artifact links.

List indexed files for a knowledgebase › path Parameters

kbId

string · required

List indexed files for a knowledgebase › query Parameters

folder_id

string · uuid

Optional folder filter within the knowledgebase.

List indexed files for a knowledgebase › Responses

Knowledgebase file index

The index-first entry point for agents and research workflows. Prefer this over crawling file endpoints one by one.

KnowledgeBaseIndex

KnowledgeBase

IndexedFile[]

Search grounding evidence elements

POST

https://api.providus.ai

/v1/knowledge-bases/{kbId}/search

Search grounding evidence elements › path Parameters

kbId

string · required

Search grounding evidence elements › Request Body

KnowledgeBaseSearchRequest

query

string · required

Lexical full-text query over parsed grounding evidence.

limit

integer · min: 1 · max: 80

Defaults to 30. Above 80 is rejected with 400.

file_ids

string[]

folder_id

string · uuid

years

integer[]

source_type

string · maxLength: 30

table_only

boolean

Restrict hits to table segments.

Search grounding evidence elements › Responses

Evidence search result

Lexical full-text search over grounding evidence. Cite the returned fileId plus segmentId.

EvidenceSearchResult

knowledge_base_id

string

index_version

string

status

string · enum

Enum values:

fresh

stale

EvidenceIndexSnapshot

EvidenceSearchHit[]

Download or list an artefact by generated link

GET

https://api.providus.ai

/v1/artifacts/{manifestId}/{artifactKey}

Generated artefact links use manifest ids and artefact keys, never raw filesystem paths.

Download or list an artefact by generated link › path Parameters

manifestId

string · required

artifactKey

string · required

Download or list an artefact by generated link › query Parameters

file

string

Download or list an artefact by generated link › Responses

Artefact bytes

string · binary

Read segment/map data from latest parse artifacts

GET

https://api.providus.ai

/v1/files/{fileId}/segments

Read segment/map data from latest parse artifacts › path Parameters

fileId

string · required

Read segment/map data from latest parse artifacts › Responses

File segments

Segment[]

A bare array, not an envelope.

A parsed segment. Fields beyond those listed are carried through from the parse artifact.

Segment

id

string

docId

string

docName

string

title

string

markdown

string

pdfUrl

string

xlsxUrl

string

EvidenceCoordinate

Page box for PDFs and images; sheet range for spreadsheets.

sourceType

string