FileSets

List File Sets

get

List all FileSets for the organization, optionally including public filesets.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

include_publicbooleanOptional

Include public filesets

Default: false

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get

/filesets/

HTTPcURLJavaScriptPython

GET /api/public/v1/filesets/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "file_sets": [
    {
      "id": "text",
      "name": "text",
      "description": "text",
      "file_count": 1,
      "indexed_file_count": 1,
      "metadata_schema": {
        "fields": [
          {
            "name": "text",
            "field_type": "string",
            "required": false,
            "description": "text",
            "extraction_hint": "text"
          }
        ]
      },
      "is_public": false,
      "created_at": "2026-05-16T02:20:15.189Z",
      "updated_at": "2026-05-16T02:20:15.189Z"
    }
  ]
}

Create File Set

post

Create a new FileSet for the organization.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

namestringRequired

Human-readable name for the FileSet

descriptionany ofOptional

Optional description of the FileSet's purpose

stringOptional

or

nullOptional

metadata_schemaany ofOptional

Optional schema for validating file metadata

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/filesets/

HTTPcURLJavaScriptPython

POST /api/public/v1/filesets/ HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 167

{
  "name": "text",
  "description": "text",
  "metadata_schema": {
    "fields": [
      {
        "name": "text",
        "field_type": "string",
        "required": true,
        "description": "text",
        "extraction_hint": "text"
      }
    ]
  }
}

{
  "id": "text",
  "name": "text",
  "description": "text",
  "file_count": 1,
  "indexed_file_count": 1,
  "metadata_schema": {
    "fields": [
      {
        "name": "text",
        "field_type": "string",
        "required": false,
        "description": "text",
        "extraction_hint": "text"
      }
    ]
  },
  "is_public": false,
  "created_at": "2026-05-16T02:20:15.189Z",
  "updated_at": "2026-05-16T02:20:15.189Z"
}

Get File Set

get

Get a specific FileSet by ID.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

file_set_idstringRequired

Responses

200

Successful Response

application/json

idstringRequired

namestringRequired

descriptionany ofRequired

stringOptional

or

nullOptional

file_countintegerRequired

indexed_file_countintegerRequired

metadata_schemaany ofOptional

or

nullOptional

is_publicbooleanOptionalDefault: false

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

get

/filesets/{file_set_id}

HTTPcURLJavaScriptPython

GET /api/public/v1/filesets/{file_set_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "description": "text",
  "file_count": 1,
  "indexed_file_count": 1,
  "metadata_schema": {
    "fields": [
      {
        "name": "text",
        "field_type": "string",
        "required": false,
        "description": "text",
        "extraction_hint": "text"
      }
    ]
  },
  "is_public": false,
  "created_at": "2026-05-16T02:20:15.189Z",
  "updated_at": "2026-05-16T02:20:15.189Z"
}

List Files In Set

get

List all files in a FileSet.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

file_set_idstringRequired

Query parameters

limitinteger · min: 1 · max: 100OptionalDefault: 10

cursorany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

next_cursorany ofOptional

stringOptional

or

nullOptional

has_morebooleanRequired

totalintegerRequired

422

Validation Error

application/json

get

/filesets/{file_set_id}/files

HTTPcURLJavaScriptPython

GET /api/public/v1/filesets/{file_set_id}/files HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "files": [
    {
      "id": "text",
      "original_file_name": "text",
      "cloud_storage_path": "text",
      "mime_type": "text",
      "size_bytes": 1,
      "character_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "gemini_file_id": "text",
      "file_created_date": "2026-05-16T02:20:15.189Z",
      "status": "PENDING",
      "status_message": "text",
      "retry_count": 0,
      "created_at": "2026-05-16T02:20:15.189Z",
      "updated_at": "2026-05-16T02:20:15.189Z"
    }
  ],
  "next_cursor": "text",
  "has_more": true,
  "total": 1
}

Add File To Set

post

Add a file to a FileSet by providing file information and metadata.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

file_set_idstringRequired

Body

application/json

file_idstringRequired

ID of the file

file_dateany ofOptional

The date of the document content. Critical for forward-looking question generation pipelines - this date determines the temporal context for forecasting questions.

string · date-timeOptional

or

nullOptional

metadataany ofOptional

Optional file-level metadata

or

nullOptional

deduplication_idany ofOptional

Optional id used to deduplicate file additions to a FileSet

stringOptional

or

nullOptional

auto_extract_metadatabooleanOptional

If true and the FileSet has a metadata schema, automatically extract metadata from file content using LLM. User-provided metadata takes precedence over extracted values.

Default: false

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/filesets/{file_set_id}/files

HTTPcURLJavaScriptPython

POST /api/public/v1/filesets/{file_set_id}/files HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 163

{
  "file_id": "text",
  "file_date": "2026-05-16T02:20:15.189Z",
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "deduplication_id": "text",
  "auto_extract_metadata": false
}

{
  "id": "text",
  "original_file_name": "text",
  "cloud_storage_path": "text",
  "mime_type": "text",
  "size_bytes": 1,
  "character_count": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "gemini_file_id": "text",
  "file_created_date": "2026-05-16T02:20:15.189Z",
  "status": "PENDING",
  "status_message": "text",
  "retry_count": 0,
  "created_at": "2026-05-16T02:20:15.189Z",
  "updated_at": "2026-05-16T02:20:15.189Z"
}

Get File Set Status

get

Get file status counts for a FileSet.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

file_set_idstringRequired

Responses

200

Successful Response

application/json

pendingintegerOptional

Files awaiting processing

Default: 0

processingintegerOptional

Files currently being processed

Default: 0

activeintegerOptional

Successfully processed files

Default: 0

failedintegerOptional

Files that failed processing

Default: 0

422

Validation Error

application/json

get

/filesets/{file_set_id}/status

HTTPcURLJavaScriptPython

GET /api/public/v1/filesets/{file_set_id}/status HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "pending": 0,
  "processing": 0,
  "active": 0,
  "failed": 0
}

Retry Failed Files

post

Retry all failed files in a FileSet.

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

file_set_idstringRequired

Body

application/json

max_retriesinteger · min: 1 · max: 10Optional

Maximum retry attempts per file

Default: 3

Responses

200

Successful Response

application/json

files_resetintegerRequired

Number of files reset to PENDING status

422

Validation Error

application/json

post

/filesets/{file_set_id}/retry-failed

HTTPcURLJavaScriptPython

POST /api/public/v1/filesets/{file_set_id}/retry-failed HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17

{
  "max_retries": 3
}

{
  "files_reset": 1
}