Files

View Files

For pre-filtering documents, using tags_v2 is preferred to using tags (which is now deprecated). If both tags_v2 and tags are specified, tags is ignored. tags_v2 enables building complex filters through the use of “AND”, “OR”, and negation logic. Take the below input as an example:

{
    "OR": [
        {
            "key": "subject",
            "value": "holy-bible",
            "negate": false
        },
        {
            "key": "person-of-interest",
            "value": "jesus christ",
            "negate": false
        },
        {
            "key": "genre",
            "value": "religion",
            "negate": true
        }
        {
            "AND": [
                {
                    "key": "subject",
                    "value": "tao-te-ching",
                    "negate": false
                },
                {
                    "key": "author",
                    "value": "lao-tzu",
                    "negate": false
                }
            ]
        }
    ]
}

In this case, files will be filtered such that:

“subject” = “holy-bible” OR
“person-of-interest” = “jesus christ” OR
“genre” != “religion” OR
“subject” = “tao-te-ching” AND “author” = “lao-tzu”

Note that the top level of the query must be either an “OR” or “AND” array. Currently, nesting is limited to 3. For tag blocks (those with “key”, “value”, and “negate” keys), the following typing rules apply:

“key” isn’t optional and must be a string
“value” isn’t optional and can be any or list[any]
“negate” is optional and must be true or false. If present and true, then the filter block is negated in the resulting query. It is false by default.

POST

user_files_v2

curl --request POST \
  --url https://api.carbon.ai/user_files_v2 \
  --header 'Content-Type: application/json' \
  --header 'authorization: <api-key>' \
  --data '{
  "pagination": {
    "limit": 10,
    "offset": 0,
    "starting_id": 0
  },
  "order_by": "updated_at",
  "order_dir": "asc",
  "filters": {
    "include_all_children": false,
    "non_synced_only": false
  },
  "include_raw_file": true,
  "include_parsed_text_file": true,
  "include_additional_files": true,
  "presigned_url_expiry_time_seconds": 3600
}'

{
  "results": [
    {
      "id": 123,
      "source": "GOOGLE_CLOUD_STORAGE",
      "organization_id": 123,
      "organization_user_id": 123,
      "organization_supplied_user_id": "<string>",
      "organization_user_data_source_id": 123,
      "external_file_id": "<string>",
      "external_url": "<string>",
      "sync_status": "DELAYED",
      "sync_error_message": "<string>",
      "last_sync": "2023-11-07T05:31:56Z",
      "tags": {},
      "file_statistics": {
        "file_format": "TXT",
        "file_size": 123,
        "num_characters": 123,
        "num_tokens": 123,
        "num_embeddings": 123,
        "mime_type": "<string>"
      },
      "file_metadata": {},
      "embedding_properties": {},
      "chunk_size": 123,
      "chunk_overlap": 123,
      "chunk_properties": {
        "set_page_as_boundary": false,
        "prepend_filename_to_chunks": false,
        "max_items_per_chunk": 123
      },
      "ocr_properties": {},
      "ocr_job_started_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "parent_id": 123,
      "enable_auto_sync": true,
      "presigned_url": "<string>",
      "parsed_text_url": "<string>",
      "additional_presigned_urls": {},
      "skip_embedding_generation": true,
      "source_created_at": "2023-11-07T05:31:56Z",
      "generate_sparse_vectors": true,
      "request_id": "<string>",
      "upload_id": "<string>",
      "sync_properties": {},
      "messages_metadata": {},
      "file_contents_deleted": false,
      "supports_cold_storage": true,
      "hot_storage_time_to_live": 123,
      "embedding_storage_status": "HOT_STORAGE",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "count": 123
}

Authorizations

authorization

string

header

required

token <token>, corresponds to temporary access tokens.

Body

application/json

pagination

object

Pagination parameters for the query.

order_by

enum<string>

The field on OrganizationUserFilesToSYnc to order the results by.

Available options:

created_at,

updated_at,

name,

last_sync,

file_size,

id

order_dir

enum<string>

The direction to order the results by.

Available options:

desc,

asc

filters

object

Filters to apply to the query.

filters.source

The source of the file. If a list is provided, the query will return files from any of the sources in the list.

Available options:

GOOGLE_CLOUD_STORAGE,

GOOGLE_DRIVE,

NOTION,

NOTION_DATABASE,

INTERCOM,

DROPBOX,

ONEDRIVE,

SHAREPOINT,

CONFLUENCE,

BOX,

ZENDESK,

ZOTERO,

S3,

AZURE_BLOB_STORAGE,

GMAIL,

OUTLOOK,

SERVICENOW,

TEXT,

CSV,

TSV,

PDF,

DOCX,

PPTX,

XLSX,

XLSM,

MD,

RTF,

JSON,

HTML,

RAW_TEXT,

WEB_SCRAPE,

RSS_FEED,

FRESHDESK,

GITBOOK,

SALESFORCE,

GITHUB,

SLACK,

GURU,

GONG,

DOCUMENT360,

JPG,

PNG,

JPEG,

MP3,

MP2,

AAC,

WAV,

FLAC,

PCM,

M4A,

OGG,

OPUS,

MPEG,

MPG,

MP4,

WMV,

AVI,

MOV,

MKV,

FLV,

WEBM,

EML,

MSG

filters.name

string | null

The name of the file. The query will return files with names that contain this string.

filters.tags

object | null

deprecated

filters.tags_v2

object | null

    Tags to filter by. Supports logical AND and OR operations. Input should be like below:
    {
        "OR": [
            {
            "key": "subject",
            "value": "holy-bible",
            "negate": false
            },
            {
                "key": "person-of-interest",
                "value": "jesus christ",
                "negate": false
            },
            {
                "key": "genre",
                "value": "fiction",
                "negate": true
            }
            {
                "AND": [
                    {
                        "key": "subject",
                        "value": "tao-te-ching",
                        "negate": true
                    },
                    {
                        "key": "author",
                        "value": "lao-tzu",
                        "negate": false
                    }
                ]
            }
        ]
    }
    For a single filter, the filter block can be placed within either an "AND" or "OR" block.

filters.ids

integer[] | null

The IDs of the files. The query will return files with these IDs.

filters.external_file_ids

string[] | null

The external file IDs of the files. The query will return files with these external file IDs.

filters.sync_statuses

enum<string>[] | null

The sync statuses of the files. The query will return files with these sync statuses.

Available options:

DELAYED,

QUEUED_FOR_SYNC,

SYNCING,

READY,

SYNC_ERROR,

EVALUATING_RESYNC,

RATE_LIMITED,

SYNC_ABORTED,

QUEUED_FOR_OCR,

READY_TO_SYNC

filters.parent_file_ids

integer[] | null

deprecated

filters.organization_user_data_source_id

integer[] | null

The organization user data source IDs of the files. The query will return files with these organization user data source IDs.

filters.embedding_generators

enum<string>[] | null

The embedding generators of the files. The query will return files with these embedding generators.

Available options:

OPENAI,

AZURE_OPENAI,

AZURE_ADA_LARGE_256,

AZURE_ADA_LARGE_1024,

AZURE_ADA_LARGE_3072,

AZURE_ADA_SMALL_512,

AZURE_ADA_SMALL_1536,

COHERE_MULTILINGUAL_V3,

VERTEX_MULTIMODAL,

OPENAI_ADA_LARGE_256,

OPENAI_ADA_LARGE_1024,

OPENAI_ADA_LARGE_3072,

OPENAI_ADA_SMALL_512,

OPENAI_ADA_SMALL_1536,

SOLAR_1_MINI

filters.root_files_only

boolean | null

If true, the query will return only root files. Cannot be true if parent_file_ids or include_all_children is specified.

filters.include_all_children

boolean

default:false

If true, the query will return all descendents of the specified parent_file_ids.

filters.non_synced_only

boolean

default:false

If true, the query will return only files that have not been synced yet.

filters.request_ids

string[] | null

Filter by request ID(s) which were used to sync the files

filters.upload_ids

string[] | null

Filter by upload ID(s) which were used to sync the files

filters.sync_error_message

string | null

The error message of the file. The query will return files with error messages that contain this string. To search for files with no error message, use an empty string.

filters.include_containers

boolean | null

If true, the query will return containers in the response. Containers are files that group other files together and have no content themselves. Default behavior is to include containers.

filters.external_urls

string[] | null

The external URLs of the files. The query will return files with these external URLs.

filters.file_types_at_source

enum<string>[] | null

Filter files based on their type at the source (for example help center tickets and articles)

Available options:

TICKET,

ARTICLE,

CONVERSATION

include_raw_file

boolean | null

If true, the query will return presigned URLs for the raw file. Only relevant for the /user_files_v2 endpoint.

include_parsed_text_file

boolean | null

If true, the query will return presigned URLs for the parsed text file. Only relevant for the /user_files_v2 endpoint.

include_additional_files

boolean | null

If true, the query will return presigned URLs for additional files. Only relevant for the /user_files_v2 endpoint.

presigned_url_expiry_time_seconds

integer

default:3600

The expiry time for the presigned URLs. Only relevant for the /user_files_v2 endpoint.

Response

200

application/json

Successful Response

results

object[]

required

results.id

integer

required

results.source

enum<string>

required

Available options:

GOOGLE_CLOUD_STORAGE,

GOOGLE_DRIVE,

NOTION,

NOTION_DATABASE,

INTERCOM,

DROPBOX,

ONEDRIVE,

SHAREPOINT,

CONFLUENCE,

BOX,

ZENDESK,

ZOTERO,

S3,

AZURE_BLOB_STORAGE,

GMAIL,

OUTLOOK,

SERVICENOW,

TEXT,

CSV,

TSV,

PDF,

DOCX,

PPTX,

XLSX,

XLSM,

MD,

RTF,

JSON,

HTML,

RAW_TEXT,

WEB_SCRAPE,

RSS_FEED,

FRESHDESK,

GITBOOK,

SALESFORCE,

GITHUB,

SLACK,

GURU,

GONG,

DOCUMENT360,

JPG,

PNG,

JPEG,

MP3,

MP2,

AAC,

WAV,

FLAC,

PCM,

M4A,

OGG,

OPUS,

MPEG,

MPG,

MP4,

WMV,

AVI,

MOV,

MKV,

FLV,

WEBM,

EML,

MSG

results.organization_id

integer

required

results.organization_user_id

integer | null

required

results.organization_supplied_user_id

string

required

results.external_file_id

string

required

results.sync_status

enum<string>

required

Available options:

DELAYED,

QUEUED_FOR_SYNC,

SYNCING,

READY,

SYNC_ERROR,

EVALUATING_RESYNC,

RATE_LIMITED,

SYNC_ABORTED,

QUEUED_FOR_OCR,

READY_TO_SYNC

results.skip_embedding_generation

boolean

required

results.supports_cold_storage

boolean

required

results.embedding_storage_status

enum<string>

required

Available options:

HOT_STORAGE,

HOT_TO_COLD,

COLD_STORAGE,

COLD_TO_HOT

results.created_at

string

required

results.updated_at

string

required

results.organization_user_data_source_id

integer | null

results.external_url

string | null

results.sync_error_message

string | null

results.last_sync

string | null

results.tags

object | null

results.file_statistics

object | null

results.file_metadata

object | null

results.embedding_properties

object | null

results.chunk_size

integer | null

results.chunk_overlap

integer | null

results.chunk_properties

object | null

results.ocr_properties

object

results.ocr_job_started_at

string | null

results.name

string | null

results.parent_id

integer | null

results.enable_auto_sync

boolean | null

results.presigned_url

string | null

results.parsed_text_url

string | null

results.additional_presigned_urls

object | null

results.source_created_at

string | null

results.generate_sparse_vectors

boolean | null

results.request_id

string | null

results.upload_id

string | null

results.sync_properties

object

results.messages_metadata

object

results.file_contents_deleted

boolean

default:false

results.hot_storage_time_to_live

integer | null

count

integer

required

Upload File via URL Delete Files V2

curl --request POST \
  --url https://api.carbon.ai/user_files_v2 \
  --header 'Content-Type: application/json' \
  --header 'authorization: <api-key>' \
  --data '{
  "pagination": {
    "limit": 10,
    "offset": 0,
    "starting_id": 0
  },
  "order_by": "updated_at",
  "order_dir": "asc",
  "filters": {
    "include_all_children": false,
    "non_synced_only": false
  },
  "include_raw_file": true,
  "include_parsed_text_file": true,
  "include_additional_files": true,
  "presigned_url_expiry_time_seconds": 3600
}'

{
  "results": [
    {
      "id": 123,
      "source": "GOOGLE_CLOUD_STORAGE",
      "organization_id": 123,
      "organization_user_id": 123,
      "organization_supplied_user_id": "<string>",
      "organization_user_data_source_id": 123,
      "external_file_id": "<string>",
      "external_url": "<string>",
      "sync_status": "DELAYED",
      "sync_error_message": "<string>",
      "last_sync": "2023-11-07T05:31:56Z",
      "tags": {},
      "file_statistics": {
        "file_format": "TXT",
        "file_size": 123,
        "num_characters": 123,
        "num_tokens": 123,
        "num_embeddings": 123,
        "mime_type": "<string>"
      },
      "file_metadata": {},
      "embedding_properties": {},
      "chunk_size": 123,
      "chunk_overlap": 123,
      "chunk_properties": {
        "set_page_as_boundary": false,
        "prepend_filename_to_chunks": false,
        "max_items_per_chunk": 123
      },
      "ocr_properties": {},
      "ocr_job_started_at": "2023-11-07T05:31:56Z",
      "name": "<string>",
      "parent_id": 123,
      "enable_auto_sync": true,
      "presigned_url": "<string>",
      "parsed_text_url": "<string>",
      "additional_presigned_urls": {},
      "skip_embedding_generation": true,
      "source_created_at": "2023-11-07T05:31:56Z",
      "generate_sparse_vectors": true,
      "request_id": "<string>",
      "upload_id": "<string>",
      "sync_properties": {},
      "messages_metadata": {},
      "file_contents_deleted": false,
      "supports_cold_storage": true,
      "hot_storage_time_to_live": 123,
      "embedding_storage_status": "HOT_STORAGE",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    }
  ],
  "count": 123
}

API Documentation

Health

Auth

Files

User

Web Scrape

Data Source

Gitbook

S3

SharePoint

GitHub

Gmail

Slack

Outlook

Organizations

Tags

Chunks / Embeddings

Retrieval

Webhooks

White Labeling

CRM

View Files

Authorizations

Body

Response