Files

File metadata, upload, version, and move operations.

List active files

GET

https://api.providus.ai

/v1/files

Returns files that have not been soft-deleted. Use GET /v1/files/trash to list soft-deleted files.

List active files › query Parameters

kb_id

string · uuid

List active files › Responses

Files

FileList

File[]

GET/v1/files

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

Example Responses

{
  "files": [
    {
      "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
      "org_id": "org_2xKq9",
      "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
      "folder_id": null,
      "filename": "master-services-agreement.pdf",
      "content_type": "application/pdf",
      "metadata": {},
      "created_at": "2026-08-19T09:12:44.000Z",
      "updated_at": "2026-08-19T09:15:41.000Z",
      "deleted_at": null,
      "current_version": {
        "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
        "version_number": 1,
        "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "byte_size": 486213,
        "page_count": 12
      }
    }
  ]
}

json

application/json

Upload file

POST

https://api.providus.ai

/v1/files

Upload file › Request Body

file

string · binary · required

knowledge_base_id

string · uuid · required

folder_id

string · uuid

filename

string

metadata

string

JSON object encoded as a string.

auto_parse

boolean

When true, Bun asks the processing plane to queue parse after upload.

parse_options

string

JSON object encoded as a string. Passed to the parse job.

Upload file › Responses

Uploaded file

parse_job, parse_usage and credit_reservation appear only when the upload also dispatched a parse.

FileUploaded

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

Job

object

Reservation

POST/v1/files

curl https://api.providus.ai/v1/files \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-docai-org-id: <api-key>' \
  --form 'file=<binary>' \
  --form 'knowledge_base_id=00000000-0000-0000-0000-000000000000' \
  --form 'folder_id=00000000-0000-0000-0000-000000000000' \
  --form 'filename=filename' \
  --form 'metadata=metadata' \
  --form 'auto_parse=true' \
  --form 'parse_options=parse_options'

Example Request Body

{
  "file": "<binary>",
  "knowledge_base_id": "00000000-0000-0000-0000-000000000000",
  "folder_id": "00000000-0000-0000-0000-000000000000",
  "filename": "filename",
  "metadata": "metadata",
  "auto_parse": true,
  "parse_options": "parse_options"
}

text

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  },
  "parse_job": {
    "job_id": "9b2f1c84-5d31-4a6e-8f10-c2a7e4d90b13",
    "status": "completed",
    "raw_status": "completed",
    "kind": "parse",
    "stage": "finished",
    "percent": 100,
    "total_pages": 12,
    "completed_pages": 12,
    "error": null,
    "result": {
      "pages": 12
    },
    "created_at": "2026-08-19T09:14:02.000Z",
    "started_at": "2026-08-19T09:14:05.000Z",
    "cancel_requested_at": null,
    "completed_at": "2026-08-19T09:15:41.000Z"
  },
  "parse_usage": {},
  "credit_reservation": {
    "id": "id",
    "status": "status",
    "estimated_credits": 0,
    "reserved_credits": 0,
    "used_credits": 0
  }
}

json

application/json

Fetch file metadata

GET

https://api.providus.ai

/v1/files/{fileId}

Fetch file metadata › path Parameters

fileId

string · required

Fetch file metadata › Responses

File

FileEnvelope

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

GET/v1/files/{fileId}

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

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  }
}

json

application/json

Soft-delete file

DELETE

https://api.providus.ai

/v1/files/{fileId}

Marks the file as deleted so it no longer appears in file lists, knowledge-base indexes, or corpus browse APIs.

Soft-delete file › path Parameters

fileId

string · required

Soft-delete file › Responses

Deleted file

Soft delete. The row is retained and POST /v1/files/{fileId}/restore undoes it.

FileDeleted

deleted

boolean

file_id

string

deleted_at

string · date-time

Rename file

PATCH

https://api.providus.ai

/v1/files/{fileId}

Updates the active file display filename. Active filenames must be unique within the same organization, knowledgebase, and folder, case-insensitive. Soft-deleted files do not block reuse.

Rename file › path Parameters

fileId

string · required

Rename file › Request Body

FileRename

filename

string · required

Rename file › Responses

File

FileEnvelope

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

PATCH/v1/files/{fileId}

curl https://api.providus.ai/v1/files/:fileId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "filename": "renamed-document.pdf"
}'

Example Request Body

{
  "filename": "renamed-document.pdf"
}

json

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  }
}

json

application/json

Permanently delete file and generated artifacts

DELETE

https://api.providus.ai

/v1/files/{fileId}/permanent

Hard-deletes the file record, file versions, processing jobs, parse/extract manifests, page versions, extraction rows, and managed filesystem root under DOCAI_ARTIFACT_ROOT. This also removes raw source, extraction JSON/markdown, page images, and crop images for every stored version.

Permanently delete file and generated artifacts › path Parameters

fileId

string · required

Permanently delete file and generated artifacts › Responses

Permanently deleted file

Unrecoverable. Removes the row, every version, and the artifact bundle.

FilePermanentlyDeleted

deleted

boolean

permanent

boolean

file_id

string

filename

string

object

Read current file version content

GET

https://api.providus.ai

/v1/files/{fileId}/content

Streams the current file version, scoped to the authenticated organization. Used by viewers for imported and uploaded source files.

Read current file version content › path Parameters

fileId

string · required

Read current file version content › Responses

File content

string · binary

Upload new file version

PUT

https://api.providus.ai

/v1/files/{fileId}/content

Upload new file version › path Parameters

fileId

string · required

Upload new file version › Request Body

file

string · binary · required

filename

string

metadata

string

JSON object encoded as a string.

auto_parse

boolean

When true, Bun queues parse for the new version.

parse_options

string

JSON object encoded as a string. Passed to the parse job.

Upload new file version › Responses

File version

FileVersionUploaded

file_id

string

object

Job

object

Reservation

PUT/v1/files/{fileId}/content

curl https://api.providus.ai/v1/files/:fileId/content \
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-docai-org-id: <api-key>' \
  --form 'file=<binary>' \
  --form 'filename=filename' \
  --form 'metadata=metadata' \
  --form 'auto_parse=true' \
  --form 'parse_options=parse_options'

Example Request Body

{
  "file": "<binary>",
  "filename": "filename",
  "metadata": "metadata",
  "auto_parse": true,
  "parse_options": "parse_options"
}

text

Example Responses

{
  "file_id": "file_id",
  "version": {},
  "parse_job": {
    "job_id": "9b2f1c84-5d31-4a6e-8f10-c2a7e4d90b13",
    "status": "completed",
    "raw_status": "completed",
    "kind": "parse",
    "stage": "finished",
    "percent": 100,
    "total_pages": 12,
    "completed_pages": 12,
    "error": null,
    "result": {
      "pages": 12
    },
    "created_at": "2026-08-19T09:14:02.000Z",
    "started_at": "2026-08-19T09:14:05.000Z",
    "cancel_requested_at": null,
    "completed_at": "2026-08-19T09:15:41.000Z"
  },
  "parse_usage": {},
  "credit_reservation": {
    "id": "id",
    "status": "status",
    "estimated_credits": 0,
    "reserved_credits": 0,
    "used_credits": 0
  }
}

json

application/json

Move file to another knowledgebase/folder

PATCH

https://api.providus.ai

/v1/files/{fileId}/move

Move file to another knowledgebase/folder › path Parameters

fileId

string · required

Move file to another knowledgebase/folder › Request Body

FileMove

knowledge_base_id

string · uuid

folder_id

string | null · uuid

Move file to another knowledgebase/folder › Responses

Moved file

FileEnvelope

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

PATCH/v1/files/{fileId}/move

curl https://api.providus.ai/v1/files/:fileId/move \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "knowledge_base_id": "00000000-0000-0000-0000-000000000000",
  "folder_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "knowledge_base_id": "00000000-0000-0000-0000-000000000000",
  "folder_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  }
}

json

application/json

Knowledge Bases File Processing

DocAI Control Plane API

Files

File metadata, upload, version, and move operations.

List active files

GET

https://api.providus.ai

/v1/files

Returns files that have not been soft-deleted. Use GET /v1/files/trash to list soft-deleted files.

List active files › query Parameters

kb_id

string · uuid

List active files › Responses

Files

FileList

File[]

GET/v1/files

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

Example Responses

{
  "files": [
    {
      "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
      "org_id": "org_2xKq9",
      "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
      "folder_id": null,
      "filename": "master-services-agreement.pdf",
      "content_type": "application/pdf",
      "metadata": {},
      "created_at": "2026-08-19T09:12:44.000Z",
      "updated_at": "2026-08-19T09:15:41.000Z",
      "deleted_at": null,
      "current_version": {
        "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
        "version_number": 1,
        "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
        "byte_size": 486213,
        "page_count": 12
      }
    }
  ]
}

json

application/json

Upload file

POST

https://api.providus.ai

/v1/files

Upload file › Request Body

file

string · binary · required

knowledge_base_id

string · uuid · required

folder_id

string · uuid

filename

string

metadata

string

JSON object encoded as a string.

auto_parse

boolean

When true, Bun asks the processing plane to queue parse after upload.

parse_options

string

JSON object encoded as a string. Passed to the parse job.

Upload file › Responses

Uploaded file

parse_job, parse_usage and credit_reservation appear only when the upload also dispatched a parse.

FileUploaded

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

Job

object

Reservation

POST/v1/files

curl https://api.providus.ai/v1/files \
  --request POST \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-docai-org-id: <api-key>' \
  --form 'file=<binary>' \
  --form 'knowledge_base_id=00000000-0000-0000-0000-000000000000' \
  --form 'folder_id=00000000-0000-0000-0000-000000000000' \
  --form 'filename=filename' \
  --form 'metadata=metadata' \
  --form 'auto_parse=true' \
  --form 'parse_options=parse_options'

Example Request Body

{
  "file": "<binary>",
  "knowledge_base_id": "00000000-0000-0000-0000-000000000000",
  "folder_id": "00000000-0000-0000-0000-000000000000",
  "filename": "filename",
  "metadata": "metadata",
  "auto_parse": true,
  "parse_options": "parse_options"
}

text

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  },
  "parse_job": {
    "job_id": "9b2f1c84-5d31-4a6e-8f10-c2a7e4d90b13",
    "status": "completed",
    "raw_status": "completed",
    "kind": "parse",
    "stage": "finished",
    "percent": 100,
    "total_pages": 12,
    "completed_pages": 12,
    "error": null,
    "result": {
      "pages": 12
    },
    "created_at": "2026-08-19T09:14:02.000Z",
    "started_at": "2026-08-19T09:14:05.000Z",
    "cancel_requested_at": null,
    "completed_at": "2026-08-19T09:15:41.000Z"
  },
  "parse_usage": {},
  "credit_reservation": {
    "id": "id",
    "status": "status",
    "estimated_credits": 0,
    "reserved_credits": 0,
    "used_credits": 0
  }
}

json

application/json

Fetch file metadata

GET

https://api.providus.ai

/v1/files/{fileId}

Fetch file metadata › path Parameters

fileId

string · required

Fetch file metadata › Responses

File

FileEnvelope

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

GET/v1/files/{fileId}

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

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  }
}

json

application/json

Soft-delete file

DELETE

https://api.providus.ai

/v1/files/{fileId}

Marks the file as deleted so it no longer appears in file lists, knowledge-base indexes, or corpus browse APIs.

Soft-delete file › path Parameters

fileId

string · required

Soft-delete file › Responses

Deleted file

Soft delete. The row is retained and POST /v1/files/{fileId}/restore undoes it.

FileDeleted

deleted

boolean

file_id

string

deleted_at

string · date-time

Rename file

PATCH

https://api.providus.ai

/v1/files/{fileId}

Updates the active file display filename. Active filenames must be unique within the same organization, knowledgebase, and folder, case-insensitive. Soft-deleted files do not block reuse.

Rename file › path Parameters

fileId

string · required

Rename file › Request Body

FileRename

filename

string · required

Rename file › Responses

File

FileEnvelope

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

PATCH/v1/files/{fileId}

curl https://api.providus.ai/v1/files/:fileId \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "filename": "renamed-document.pdf"
}'

Example Request Body

{
  "filename": "renamed-document.pdf"
}

json

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  }
}

json

application/json

Permanently delete file and generated artifacts

DELETE

https://api.providus.ai

/v1/files/{fileId}/permanent

Permanently delete file and generated artifacts › path Parameters

fileId

string · required

Permanently delete file and generated artifacts › Responses

Permanently deleted file

Unrecoverable. Removes the row, every version, and the artifact bundle.

FilePermanentlyDeleted

deleted

boolean

permanent

boolean

file_id

string

filename

string

object

Read current file version content

GET

https://api.providus.ai

/v1/files/{fileId}/content

Streams the current file version, scoped to the authenticated organization. Used by viewers for imported and uploaded source files.

Read current file version content › path Parameters

fileId

string · required

Read current file version content › Responses

File content

string · binary

Upload new file version

PUT

https://api.providus.ai

/v1/files/{fileId}/content

Upload new file version › path Parameters

fileId

string · required

Upload new file version › Request Body

file

string · binary · required

filename

string

metadata

string

JSON object encoded as a string.

auto_parse

boolean

When true, Bun queues parse for the new version.

parse_options

string

JSON object encoded as a string. Passed to the parse job.

Upload new file version › Responses

File version

FileVersionUploaded

file_id

string

object

Job

object

Reservation

PUT/v1/files/{fileId}/content

curl https://api.providus.ai/v1/files/:fileId/content \
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-docai-org-id: <api-key>' \
  --form 'file=<binary>' \
  --form 'filename=filename' \
  --form 'metadata=metadata' \
  --form 'auto_parse=true' \
  --form 'parse_options=parse_options'

Example Request Body

{
  "file": "<binary>",
  "filename": "filename",
  "metadata": "metadata",
  "auto_parse": true,
  "parse_options": "parse_options"
}

text

Example Responses

{
  "file_id": "file_id",
  "version": {},
  "parse_job": {
    "job_id": "9b2f1c84-5d31-4a6e-8f10-c2a7e4d90b13",
    "status": "completed",
    "raw_status": "completed",
    "kind": "parse",
    "stage": "finished",
    "percent": 100,
    "total_pages": 12,
    "completed_pages": 12,
    "error": null,
    "result": {
      "pages": 12
    },
    "created_at": "2026-08-19T09:14:02.000Z",
    "started_at": "2026-08-19T09:14:05.000Z",
    "cancel_requested_at": null,
    "completed_at": "2026-08-19T09:15:41.000Z"
  },
  "parse_usage": {},
  "credit_reservation": {
    "id": "id",
    "status": "status",
    "estimated_credits": 0,
    "reserved_credits": 0,
    "used_credits": 0
  }
}

json

application/json

Move file to another knowledgebase/folder

PATCH

https://api.providus.ai

/v1/files/{fileId}/move

Move file to another knowledgebase/folder › path Parameters

fileId

string · required

Move file to another knowledgebase/folder › Request Body

FileMove

knowledge_base_id

string · uuid

folder_id

string | null · uuid

Move file to another knowledgebase/folder › Responses

Moved file

FileEnvelope

File

File row plus its current version. Additional columns may appear; the properties below are the stable contract.

PATCH/v1/files/{fileId}/move

curl https://api.providus.ai/v1/files/:fileId/move \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'x-docai-org-id: <api-key>' \
  --data '{
  "knowledge_base_id": "00000000-0000-0000-0000-000000000000",
  "folder_id": "00000000-0000-0000-0000-000000000000"
}'

Example Request Body

{
  "knowledge_base_id": "00000000-0000-0000-0000-000000000000",
  "folder_id": "00000000-0000-0000-0000-000000000000"
}

json

Example Responses

{
  "file": {
    "id": "5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52",
    "org_id": "org_2xKq9",
    "knowledge_base_id": "6f3b9d02-77c1-4e58-a0d4-1b9e2c7f4a86",
    "folder_id": null,
    "filename": "master-services-agreement.pdf",
    "content_type": "application/pdf",
    "metadata": {},
    "created_at": "2026-08-19T09:12:44.000Z",
    "updated_at": "2026-08-19T09:15:41.000Z",
    "deleted_at": null,
    "current_version": {
      "id": "8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22",
      "version_number": 1,
      "storage_path": "org_2xKq9/files/5d7c0a11-2f48-4c39-9b7a-6e0d3f8c1a52/versions/8a1e5b73-9c02-4d6f-b3a8-5f7c1d904e22/master-services-agreement.pdf",
      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
      "byte_size": 486213,
      "page_count": 12
    }
  }
}

json

application/json

Knowledge Bases File Processing