konfig / carbon-php-sdk
Connect external data to LLMs, no matter the source.
Requires
- php: ^8.0
- ext-curl: *
- ext-json: *
- ext-mbstring: *
- guzzlehttp/guzzle: ^7.3
- guzzlehttp/psr7: ^1.7 || ^2.0
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.5
- phpunit/phpunit: ^8.0 || ^9.0
README
Carbon
Connect external data to LLMs, no matter the source.
Table of Contents
- Installation & Usage
- Getting Started
- Reference
carbon.auth.getAccessToken
carbon.auth.getWhiteLabeling
carbon.dataSources.queryUserDataSources
carbon.dataSources.revokeAccessToken
carbon.embeddings.getDocuments
carbon.embeddings.getEmbeddingsAndChunks
carbon.embeddings.uploadChunksAndEmbeddings
carbon.files.createUserFileTags
carbon.files.delete
carbon.files.deleteFileTags
carbon.files.deleteMany
carbon.files.deleteV2
carbon.files.getParsedFile
carbon.files.getRawFile
carbon.files.queryUserFiles
carbon.files.queryUserFilesDeprecated
carbon.files.resync
carbon.files.upload
carbon.files.uploadFromUrl
carbon.files.uploadText
carbon.health.check
carbon.integrations.connectDataSource
carbon.integrations.connectFreshdesk
carbon.integrations.connectGitbook
carbon.integrations.createAwsIamUser
carbon.integrations.getOauthUrl
carbon.integrations.listConfluencePages
carbon.integrations.listDataSourceItems
carbon.integrations.listFolders
carbon.integrations.listGitbookSpaces
carbon.integrations.listLabels
carbon.integrations.listOutlookCategories
carbon.integrations.syncConfluence
carbon.integrations.syncDataSourceItems
carbon.integrations.syncFiles
carbon.integrations.syncGitHub
carbon.integrations.syncGitbook
carbon.integrations.syncGmail
carbon.integrations.syncOutlook
carbon.integrations.syncRssFeed
carbon.integrations.syncS3Files
carbon.organizations.get
carbon.users.delete
carbon.users.get
carbon.users.toggleUserFeatures
carbon.users.updateUsers
carbon.utilities.fetchUrls
carbon.utilities.fetchYoutubeTranscripts
carbon.utilities.processSitemap
carbon.utilities.scrapeSitemap
carbon.utilities.scrapeWeb
carbon.utilities.searchUrls
carbon.webhooks.addUrl
carbon.webhooks.deleteUrl
carbon.webhooks.urls
Installation & Usage
Requirements
This library requires PHP ^8.0
Composer
To install the bindings via Composer, add the following to composer.json
:
{ "repositories": [ { "type": "vcs", "url": "https://github.com/Carbon-for-Developers/carbon-php-sdk.git" } ], "require": { "konfig/carbon-php-sdk": "0.1.22" } }
Then run composer install
Manual Installation
Download the files and include autoload.php
:
<?php require_once('/path/to/carbon-php-sdk/vendor/autoload.php');
Getting Started
Please follow the installation procedure and then run the following:
<?php require_once(__DIR__ . '/vendor/autoload.php'); // 1) Get an access token for a customer $carbon = new \Carbon\Client( apiKey: "API_KEY", customerId: "CUSTOMER_ID", ); $result = $carbon->auth->getAccessToken(); # 2) Use the access token to authenticate moving forward $carbon = new \Carbon\Client(accessToken: $token->getAccessToken()); # use SDK as usual $whiteLabeling = $carbon->auth->getWhiteLabeling(); # etc.
Reference
carbon.auth.getAccessToken
Get Access Token
🛠️ Usage
$result = $carbon->auth->getAccessToken();
🔄 Return
🌐 Endpoint
/auth/v1/access_token
GET
carbon.auth.getWhiteLabeling
Returns whether or not the organization is white labeled and which integrations are white labeled
:param current_user: the current user :param db: the database session :return: a WhiteLabelingResponse
🛠️ Usage
$result = $carbon->auth->getWhiteLabeling();
🔄 Return
🌐 Endpoint
/auth/v1/white_labeling
GET
carbon.dataSources.queryUserDataSources
User Data Sources
🛠️ Usage
$result = $carbon->dataSources->queryUserDataSources( pagination: [ "limit" => 10, "offset" => 0, ], order_by: "created_at", order_dir: "desc", filters: [ "source" => "GOOGLE_DRIVE", ] );
⚙️ Parameters
pagination: Pagination
order_by:
order_dir:
filters: OrganizationUserDataSourceFilters
🔄 Return
OrganizationUserDataSourceResponse
🌐 Endpoint
/user_data_sources
POST
carbon.dataSources.revokeAccessToken
Revoke Access Token
🛠️ Usage
$result = $carbon->dataSources->revokeAccessToken( data_source_id: 1 );
⚙️ Parameters
data_source_id: int
🔄 Return
🌐 Endpoint
/revoke_access_token
POST
carbon.embeddings.getDocuments
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
orfalse
. If present andtrue
, then the filter block is negated in the resulting query. It isfalse
by default.
When querying embeddings, you can optionally specify the media_type
parameter in your request. By default (if
not set), it is equal to "TEXT". This means that the query will be performed over files that have
been parsed as text (for now, this covers all files except image files). If it is equal to "IMAGE",
the query will be performed over image files (for now, .jpg
and .png
files). You can think of this
field as an additional filter on top of any filters set in file_ids
and
When hybrid_search
is set to true, a combination of keyword search and semantic search are used to rank
and select candidate embeddings during information retrieval. By default, these search methods are weighted
equally during the ranking process. To adjust the weight (or "importance") of each search method, you can use
the hybrid_search_tuning_parameters
property. The description for the different tuning parameters are:
weight_a
: weight to assign to semantic searchweight_b
: weight to assign to keyword search
You must ensure that sum(weight_a, weight_b,..., weight_n)
for all n weights is equal to 1. The equality
has an error tolerance of 0.001 to account for possible floating point issues.
In order to use hybrid search for a customer across a set of documents, two flags need to be enabled:
- Use the
/modify_user_configuration
endpoint to to enablesparse_vectors
for the customer. The payload body for this request is below:
{
"configuration_key_name": "sparse_vectors",
"value": {
"enabled": true
}
}
- Make sure hybrid search is enabled for the documents across which you want to perform the search. For the
/uploadfile
endpoint, this can be done by setting the following query parameter:generate_sparse_vectors=true
Carbon supports multiple models for use in generating embeddings for files. For images, we support Vertex AI's
multimodal model; for text, we support OpenAI's text-embedding-ada-002
and Cohere's embed-multilingual-v3.0.
The model can be specified via the embedding_model
parameter (in the POST body for /embeddings
, and a query
parameter in /uploadfile
). If no model is supplied, the text-embedding-ada-002
is used by default. When performing
embedding queries, embeddings from files that used the specified model will be considered in the query.
For example, if files A and B have embeddings generated with OPENAI
, and files C and D have embeddings generated with
COHERE_MULTILINGUAL_V3
, then by default, queries will only consider files A and B. If COHERE_MULTILINGUAL_V3
is
specified as the embedding_model
in /embeddings
, then only files C and D will be considered. Make sure that
the set of all files you want considered for a query have embeddings generated via the same model. For now, do not
set VERTEX_MULTIMODAL
as an embedding_model
. This model is used automatically by Carbon when it detects an image file.
🛠️ Usage
$result = $carbon->embeddings->getDocuments( query: "a", k: 1, tags: [ "key": "string_example", ], query_vector: [ 3.14 ], file_ids: [ 1 ], parent_file_ids: [ 1 ], include_all_children: False, tags_v2: [ ], include_tags: True, include_vectors: True, include_raw_file: True, hybrid_search: True, hybrid_search_tuning_parameters: [ "weight_a" => 0.5, "weight_b" => 0.5, ], media_type: "TEXT", embedding_model: "OPENAI" );
⚙️ Parameters
query: string
Query for which to get related chunks and embeddings.
k: int
Number of related chunks to return.
tags: array<string, Tags1
>
A set of tags to limit the search to. Deprecated and may be removed in the future.
query_vector: float
[]
Optional query vector for which to get related chunks and embeddings. It must have been generated by the same model used to generate the embeddings across which the search is being conducted. Cannot provide both query
and query_vector
.
file_ids: int
[]
Optional list of file IDs to limit the search to
parent_file_ids: int
[]
Optional list of parent file IDs to limit the search to. A parent file describes a file to which another file belongs (e.g. a folder)
include_all_children: bool
Flag to control whether or not to include all children of filtered files in the embedding search.
tags_v2: object
A set of tags to limit the search to. Use this instead of tags
, which is deprecated.
include_tags: bool
Flag to control whether or not to include tags for each chunk in the response.
include_vectors: bool
Flag to control whether or not to include embedding vectors in the response.
include_raw_file: bool
Flag to control whether or not to include a signed URL to the raw file containing each chunk in the response.
hybrid_search: bool
Flag to control whether or not to perform hybrid search.
hybrid_search_tuning_parameters: HybridSearchTuningParamsNullable
media_type:
embedding_model:
🔄 Return
🌐 Endpoint
/embeddings
POST
carbon.embeddings.getEmbeddingsAndChunks
Retrieve Embeddings And Content
🛠️ Usage
$result = $carbon->embeddings->getEmbeddingsAndChunks( filters: [ "user_file_id" => 1, "embedding_model" => "OPENAI", ], pagination: [ "limit" => 10, "offset" => 0, ], order_by: "created_at", order_dir: "desc", include_vectors: False );
⚙️ Parameters
filters: EmbeddingsAndChunksFilters
pagination: Pagination
order_by:
order_dir:
include_vectors: bool
🔄 Return
🌐 Endpoint
/text_chunks
POST
carbon.embeddings.uploadChunksAndEmbeddings
Upload Chunks And Embeddings
🛠️ Usage
$result = $carbon->embeddings->uploadChunksAndEmbeddings( embedding_model: "OPENAI", chunks_and_embeddings: [ [ "file_id" => 1, "chunks_and_embeddings" => [ [ "chunk_number" => 1, "chunk" => "chunk_example", ] ], ] ], overwrite_existing: False, chunks_only: False, custom_credentials: [] );
⚙️ Parameters
embedding_model:
chunks_and_embeddings: SingleChunksAndEmbeddingsUploadInput
[]
overwrite_existing: bool
chunks_only: bool
custom_credentials: object
🔄 Return
🌐 Endpoint
/upload_chunks_and_embeddings
POST
carbon.files.createUserFileTags
A tag is a key-value pair that can be added to a file. This pair can then be used for searches (e.g. embedding searches) in order to narrow down the scope of the search. A file can have any number of tags. The following are reserved keys that cannot be used:
- db_embedding_id
- organization_id
- user_id
- organization_user_file_id
Carbon currently supports two data types for tag values - string
and list<string>
.
Keys can only be string
. If values other than string
and list<string>
are used,
they're automatically converted to strings (e.g. 4 will become "4").
🛠️ Usage
$result = $carbon->files->createUserFileTags( tags: [ "key": "string_example", ], organization_user_file_id: 1 );
⚙️ Parameters
tags: array<string, Tags1
>
organization_user_file_id: int
🔄 Return
🌐 Endpoint
/create_user_file_tags
POST
carbon.files.delete
Delete File Endpoint
🛠️ Usage
$result = $carbon->files->delete( file_id: 1 );
⚙️ Parameters
file_id: int
🔄 Return
🌐 Endpoint
/deletefile/{file_id}
DELETE
carbon.files.deleteFileTags
Delete File Tags
🛠️ Usage
$result = $carbon->files->deleteFileTags( tags: [ "string_example" ], organization_user_file_id: 1 );
⚙️ Parameters
tags: string
[]
organization_user_file_id: int
🔄 Return
🌐 Endpoint
/delete_user_file_tags
POST
carbon.files.deleteMany
Delete Files Endpoint
🛠️ Usage
$result = $carbon->files->deleteMany( file_ids: [ 1 ], sync_statuses: [ "string_example" ], delete_non_synced_only: False, send_webhook: False, delete_child_files: False );
⚙️ Parameters
file_ids: int
[]
sync_statuses: []
delete_non_synced_only: bool
send_webhook: bool
delete_child_files: bool
🔄 Return
🌐 Endpoint
/delete_files
POST
carbon.files.deleteV2
Delete Files V2 Endpoint
🛠️ Usage
$result = $carbon->files->deleteV2( filters: [ "include_all_children" => False, "non_synced_only" => False, ], send_webhook: False );
⚙️ Parameters
filters: OrganizationUserFilesToSyncFilters
send_webhook: bool
🔄 Return
🌐 Endpoint
/delete_files_v2
POST
carbon.files.getParsedFile
This route is deprecated. Use /user_files_v2
instead.
🛠️ Usage
$result = $carbon->files->getParsedFile( file_id: 1 );
⚙️ Parameters
file_id: int
🔄 Return
🌐 Endpoint
/parsed_file/{file_id}
GET
carbon.files.getRawFile
This route is deprecated. Use /user_files_v2
instead.
🛠️ Usage
$result = $carbon->files->getRawFile( file_id: 1 );
⚙️ Parameters
file_id: int
🔄 Return
🌐 Endpoint
/raw_file/{file_id}
GET
carbon.files.queryUserFiles
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
orfalse
. If present andtrue
, then the filter block is negated in the resulting query. It isfalse
by default.
🛠️ Usage
$result = $carbon->files->queryUserFiles( pagination: [ "limit" => 10, "offset" => 0, ], order_by: "created_at", order_dir: "desc", filters: [ "include_all_children" => False, "non_synced_only" => False, ], include_raw_file: True, include_parsed_text_file: True, include_additional_files: True );
⚙️ Parameters
pagination: Pagination
order_by:
order_dir:
filters: OrganizationUserFilesToSyncFilters
include_raw_file: bool
include_parsed_text_file: bool
include_additional_files: bool
🔄 Return
🌐 Endpoint
/user_files_v2
POST
carbon.files.queryUserFilesDeprecated
This route is deprecated. Use /user_files_v2
instead.
🛠️ Usage
$result = $carbon->files->queryUserFilesDeprecated( pagination: [ "limit" => 10, "offset" => 0, ], order_by: "created_at", order_dir: "desc", filters: [ "include_all_children" => False, "non_synced_only" => False, ], include_raw_file: True, include_parsed_text_file: True, include_additional_files: True );
⚙️ Parameters
pagination: Pagination
order_by:
order_dir:
filters: OrganizationUserFilesToSyncFilters
include_raw_file: bool
include_parsed_text_file: bool
include_additional_files: bool
🔄 Return
🌐 Endpoint
/user_files
POST
carbon.files.resync
Resync File
🛠️ Usage
$result = $carbon->files->resync( file_id: 1, chunk_size: 1, chunk_overlap: 1, force_embedding_generation: False );
⚙️ Parameters
file_id: int
chunk_size: int
chunk_overlap: int
force_embedding_generation: bool
🔄 Return
🌐 Endpoint
/resync_file
POST
carbon.files.upload
This endpoint is used to directly upload local files to Carbon. The POST
request should be a multipart form request.
Note that the set_page_as_boundary
query parameter is applicable only to PDFs for now. When this value is set,
PDF chunks are at most one page long. Additional information can be retrieved for each chunk, however, namely the coordinates
of the bounding box around the chunk (this can be used for things like text highlighting). Following is a description
of all possible query parameters:
chunk_size
: the chunk size (in tokens) applied when splitting the documentchunk_overlap
: the chunk overlap (in tokens) applied when splitting the documentskip_embedding_generation
: whether or not to skip the generation of chunks and embeddingsset_page_as_boundary
: described aboveembedding_model
: the model used to generate embeddings for the document chunksuse_ocr
: whether or not to use OCR as a preprocessing step prior to generating chunks (only valid for PDFs currently)generate_sparse_vectors
: whether or not to generate sparse vectors for the file. Required for hybrid search.prepend_filename_to_chunks
: whether or not to prepend the filename to the chunk text
Carbon supports multiple models for use in generating embeddings for files. For images, we support Vertex AI's
multimodal model; for text, we support OpenAI's text-embedding-ada-002
and Cohere's embed-multilingual-v3.0.
The model can be specified via the embedding_model
parameter (in the POST body for /embeddings
, and a query
parameter in /uploadfile
). If no model is supplied, the text-embedding-ada-002
is used by default. When performing
embedding queries, embeddings from files that used the specified model will be considered in the query.
For example, if files A and B have embeddings generated with OPENAI
, and files C and D have embeddings generated with
COHERE_MULTILINGUAL_V3
, then by default, queries will only consider files A and B. If COHERE_MULTILINGUAL_V3
is
specified as the embedding_model
in /embeddings
, then only files C and D will be considered. Make sure that
the set of all files you want considered for a query have embeddings generated via the same model. For now, do not
set VERTEX_MULTIMODAL
as an embedding_model
. This model is used automatically by Carbon when it detects an image file.
🛠️ Usage
$result = $carbon->files->upload( file: open('/path/to/file', 'rb'), chunk_size: 1, chunk_overlap: 1, skip_embedding_generation: False, set_page_as_boundary: False, embedding_model: "OPENAI", use_ocr: False, generate_sparse_vectors: False, prepend_filename_to_chunks: False, max_items_per_chunk: 1, parse_pdf_tables_with_ocr: False );
⚙️ Parameters
file: \SplFileObject
chunk_size: int
Chunk size in tiktoken tokens to be used when processing file.
chunk_overlap: int
Chunk overlap in tiktoken tokens to be used when processing file.
skip_embedding_generation: bool
Flag to control whether or not embeddings should be generated and stored when processing file.
set_page_as_boundary: bool
Flag to control whether or not to set the a page's worth of content as the maximum amount of content that can appear in a chunk. Only valid for PDFs. See description route description for more information.
embedding_model:
Embedding model that will be used to embed file chunks.
use_ocr: bool
Whether or not to use OCR when processing files. Only valid for PDFs. Useful for documents with tables, images, and/or scanned text.
generate_sparse_vectors: bool
Whether or not to generate sparse vectors for the file. This is required for the file to be a candidate for hybrid search.
prepend_filename_to_chunks: bool
Whether or not to prepend the file's name to chunks.
max_items_per_chunk: int
Number of objects per chunk. For csv, tsv, xlsx, and json files only.
parse_pdf_tables_with_ocr: bool
Whether to use rich table parsing when use_ocr
is enabled.
🔄 Return
🌐 Endpoint
/uploadfile
POST
carbon.files.uploadFromUrl
Create Upload File From Url
🛠️ Usage
$result = $carbon->files->uploadFromUrl( url: "string_example", file_name: "string_example", chunk_size: 1, chunk_overlap: 1, skip_embedding_generation: False, set_page_as_boundary: False, embedding_model: "OPENAI", generate_sparse_vectors: False, use_textract: False, prepend_filename_to_chunks: False, max_items_per_chunk: 1, parse_pdf_tables_with_ocr: False );
⚙️ Parameters
url: string
file_name: string
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
set_page_as_boundary: bool
embedding_model:
generate_sparse_vectors: bool
use_textract: bool
prepend_filename_to_chunks: bool
max_items_per_chunk: int
Number of objects per chunk. For csv, tsv, xlsx, and json files only.
parse_pdf_tables_with_ocr: bool
🔄 Return
🌐 Endpoint
/upload_file_from_url
POST
carbon.files.uploadText
Carbon supports multiple models for use in generating embeddings for files. For images, we support Vertex AI's
multimodal model; for text, we support OpenAI's text-embedding-ada-002
and Cohere's embed-multilingual-v3.0.
The model can be specified via the embedding_model
parameter (in the POST body for /embeddings
, and a query
parameter in /uploadfile
). If no model is supplied, the text-embedding-ada-002
is used by default. When performing
embedding queries, embeddings from files that used the specified model will be considered in the query.
For example, if files A and B have embeddings generated with OPENAI
, and files C and D have embeddings generated with
COHERE_MULTILINGUAL_V3
, then by default, queries will only consider files A and B. If COHERE_MULTILINGUAL_V3
is
specified as the embedding_model
in /embeddings
, then only files C and D will be considered. Make sure that
the set of all files you want considered for a query have embeddings generated via the same model. For now, do not
set VERTEX_MULTIMODAL
as an embedding_model
. This model is used automatically by Carbon when it detects an image file.
🛠️ Usage
$result = $carbon->files->uploadText( contents: "string_example", name: "string_example", chunk_size: 1, chunk_overlap: 1, skip_embedding_generation: False, overwrite_file_id: 1, embedding_model: "OPENAI", generate_sparse_vectors: False );
⚙️ Parameters
contents: string
name: string
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
overwrite_file_id: int
embedding_model:
generate_sparse_vectors: bool
🔄 Return
🌐 Endpoint
/upload_text
POST
carbon.health.check
Health
🛠️ Usage
$result = $carbon->health->check();
🔄 Return
object
🌐 Endpoint
/health
GET
carbon.integrations.connectDataSource
Connect Data Source
🛠️ Usage
$result = $carbon->integrations->connectDataSource( authentication: [ "source" => "GOOGLE_DRIVE", "access_token" => "access_token_example", ], sync_options: [ "chunk_size" => 1500, "chunk_overlap" => 20, "skip_embedding_generation" => False, "embedding_model" => "OPENAI", "generate_sparse_vectors" => False, "prepend_filename_to_chunks" => False, "sync_files_on_connection" => True, "set_page_as_boundary" => False, "request_id" => "e8fddc9a-4810-48b2-b1b5-b1ec0159625a", "enable_file_picker" => True, ] );
⚙️ Parameters
authentication: AuthenticationProperty
sync_options: SyncOptions
🔄 Return
🌐 Endpoint
/integrations/connect
POST
carbon.integrations.connectFreshdesk
Refer this article to obtain an API key https://support.freshdesk.com/en/support/solutions/articles/215517. Make sure that your API key has the permission to read solutions from your account and you are on a paid plan. Once you have an API key, you can make a request to this endpoint along with your freshdesk domain. This will trigger an automatic sync of the articles in your "solutions" tab. Additional parameters below can be used to associate data with the synced articles or modify the sync behavior.
🛠️ Usage
$result = $carbon->integrations->connectFreshdesk( domain: "string_example", api_key: "string_example", tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, sync_files_on_connection: True, request_id: "string_example" );
⚙️ Parameters
domain: string
api_key: string
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
sync_files_on_connection: bool
request_id: string
🔄 Return
🌐 Endpoint
/integrations/freshdesk
POST
carbon.integrations.connectGitbook
You will need an access token to connect your Gitbook account. Note that the permissions will be defined by the user generating access token so make sure you have the permission to access spaces you will be syncing. Refer this article for more details https://developer.gitbook.com/gitbook-api/authentication. Additionally, you need to specify the name of organization you will be syncing data from.
🛠️ Usage
$result = $carbon->integrations->connectGitbook( organization: "string_example", access_token: "string_example", tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, sync_files_on_connection: True, request_id: "string_example" );
⚙️ Parameters
organization: string
access_token: string
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
sync_files_on_connection: bool
request_id: string
🔄 Return
🌐 Endpoint
/integrations/gitbook
POST
carbon.integrations.createAwsIamUser
Create a new IAM user with permissions to:
- List all buckets.
- Read from the specific buckets and objects to sync with Carbon. Ensure any future buckets or objects carry the same permissions.
🛠️ Usage
$result = $carbon->integrations->createAwsIamUser( access_key: "string_example", access_key_secret: "string_example" );
⚙️ Parameters
access_key: string
access_key_secret: string
🔄 Return
🌐 Endpoint
/integrations/s3
POST
carbon.integrations.getOauthUrl
This endpoint can be used to generate the following URLs
- An OAuth URL for OAuth based connectors
- A file syncing URL which skips the OAuth flow if the user already has a valid access token and takes them to the success state.
🛠️ Usage
$result = $carbon->integrations->getOauthUrl( service: "GOOGLE_DRIVE", tags: None, scope: "string_example", chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", zendesk_subdomain: "string_example", microsoft_tenant: "string_example", sharepoint_site_name: "string_example", confluence_subdomain: "string_example", generate_sparse_vectors: False, prepend_filename_to_chunks: False, max_items_per_chunk: 1, salesforce_domain: "string_example", sync_files_on_connection: True, set_page_as_boundary: False, data_source_id: 1, connecting_new_account: False, request_id: "76343a7e-0175-49f8-957c-e1133ae388ac", use_ocr: False, parse_pdf_tables_with_ocr: False, enable_file_picker: True );
⚙️ Parameters
service:
tags:
scope: string
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
zendesk_subdomain: string
microsoft_tenant: string
sharepoint_site_name: string
confluence_subdomain: string
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
max_items_per_chunk: int
Number of objects per chunk. For csv, tsv, xlsx, and json files only.
salesforce_domain: string
sync_files_on_connection: bool
Used to specify whether Carbon should attempt to sync all your files automatically when authorization is complete. This is only supported for a subset of connectors and will be ignored for the rest. Supported connectors: Intercom, Zendesk, Gitbook, Confluence, Salesforce, Freshdesk
set_page_as_boundary: bool
data_source_id: int
Used to specify a data source to sync from if you have multiple connected. It can be skipped if you only have one data source of that type connected or are connecting a new account.
connecting_new_account: bool
Used to connect a new data source. If not specified, we will attempt to create a sync URL for an existing data source based on type and ID.
request_id: string
This request id will be added to all files that get synced using the generated OAuth URL
use_ocr: bool
Enable OCR for files that support it. Supported formats: pdf
parse_pdf_tables_with_ocr: bool
enable_file_picker: bool
Enable integration's file picker for sources that support it. Supported sources: DROPBOX, BOX, ONEDRIVE, GOOGLE_DRIVE, SHAREPOINT
🔄 Return
🌐 Endpoint
/integrations/oauth_url
POST
carbon.integrations.listConfluencePages
To begin listing a user's Confluence pages, at least a data_source_id
of a connected
Confluence account must be specified. This base request returns a list of root pages for
every space the user has access to in a Confluence instance. To traverse further down
the user's page directory, additional requests to this endpoint can be made with the same
data_source_id
and with parent_id
set to the id of page from a previous request. For
convenience, the has_children
property in each directory item in the response list will
flag which pages will return non-empty lists of pages when set as the parent_id
.
🛠️ Usage
$result = $carbon->integrations->listConfluencePages( data_source_id: 1, parent_id: "string_example" );
⚙️ Parameters
data_source_id: int
parent_id: string
🔄 Return
🌐 Endpoint
/integrations/confluence/list
POST
carbon.integrations.listDataSourceItems
List Data Source Items
🛠️ Usage
$result = $carbon->integrations->listDataSourceItems( data_source_id: 1, parent_id: "string_example", filters: [ ], pagination: [ "limit" => 10, "offset" => 0, ] );
⚙️ Parameters
data_source_id: int
parent_id: string
filters: ListItemsFiltersNullable
pagination: Pagination
🔄 Return
🌐 Endpoint
/integrations/items/list
POST
carbon.integrations.listFolders
After connecting your Outlook account, you can use this endpoint to list all of your folders on outlook. This includes both system folders like "inbox" and user created folders.
🛠️ Usage
$result = $carbon->integrations->listFolders( data_source_id: 1 );
⚙️ Parameters
data_source_id: int
🔄 Return
object
🌐 Endpoint
/integrations/outlook/user_folders
GET
carbon.integrations.listGitbookSpaces
After connecting your Gitbook account, you can use this endpoint to list all of your spaces under current organization.
🛠️ Usage
$result = $carbon->integrations->listGitbookSpaces( data_source_id: 1 );
⚙️ Parameters
data_source_id: int
🔄 Return
object
🌐 Endpoint
/integrations/gitbook/spaces
GET
carbon.integrations.listLabels
After connecting your Gmail account, you can use this endpoint to list all of your labels. User created labels will have the type "user" and Gmail's default labels will have the type "system"
🛠️ Usage
$result = $carbon->integrations->listLabels( data_source_id: 1 );
⚙️ Parameters
data_source_id: int
🔄 Return
object
🌐 Endpoint
/integrations/gmail/user_labels
GET
carbon.integrations.listOutlookCategories
After connecting your Outlook account, you can use this endpoint to list all of your categories on outlook. We currently support listing up to 250 categories.
🛠️ Usage
$result = $carbon->integrations->listOutlookCategories( data_source_id: 1 );
⚙️ Parameters
data_source_id: int
🔄 Return
object
🌐 Endpoint
/integrations/outlook/user_categories
GET
carbon.integrations.syncConfluence
After listing pages in a user's Confluence account, the set of selected page ids
and the
connected account's data_source_id
can be passed into this endpoint to sync them into
Carbon. Additional parameters listed below can be used to associate data to the selected
pages or alter the behavior of the sync.
🛠️ Usage
$result = $carbon->integrations->syncConfluence( data_source_id: 1, ids: [ "string_example" ], tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, max_items_per_chunk: 1, set_page_as_boundary: False, request_id: "74c95466-42b2-4213-ae36-bfafbaecfcf5", use_ocr: False, parse_pdf_tables_with_ocr: False );
⚙️ Parameters
data_source_id: int
ids: IdsProperty
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
max_items_per_chunk: int
Number of objects per chunk. For csv, tsv, xlsx, and json files only.
set_page_as_boundary: bool
request_id: string
use_ocr: bool
parse_pdf_tables_with_ocr: bool
🔄 Return
🌐 Endpoint
/integrations/confluence/sync
POST
carbon.integrations.syncDataSourceItems
Sync Data Source Items
🛠️ Usage
$result = $carbon->integrations->syncDataSourceItems( data_source_id: 1 );
⚙️ Parameters
data_source_id: int
🔄 Return
🌐 Endpoint
/integrations/items/sync
POST
carbon.integrations.syncFiles
After listing files and folders via /integrations/items/sync and integrations/items/list, use the selected items' external ids as the ids in this endpoint to sync them into Carbon. Sharepoint items take an additional parameter root_id, which identifies the drive the file or folder is in and is stored in root_external_id. That additional paramter is optional and excluding it will tell the sync to assume the item is stored in the default Documents drive.
🛠️ Usage
$result = $carbon->integrations->syncFiles( data_source_id: 1, ids: [ "string_example" ], tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, max_items_per_chunk: 1, set_page_as_boundary: False, request_id: "74c95466-42b2-4213-ae36-bfafbaecfcf5", use_ocr: False, parse_pdf_tables_with_ocr: False );
⚙️ Parameters
data_source_id: int
ids: IdsProperty
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
max_items_per_chunk: int
Number of objects per chunk. For csv, tsv, xlsx, and json files only.
set_page_as_boundary: bool
request_id: string
use_ocr: bool
parse_pdf_tables_with_ocr: bool
🔄 Return
🌐 Endpoint
/integrations/files/sync
POST
carbon.integrations.syncGitHub
Refer this article to obtain an access token https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens. Make sure that your access token has the permission to read content from your desired repos. Note that if your access token expires you will need to manually update it through this endpoint.
🛠️ Usage
$result = $carbon->integrations->syncGitHub( username: "string_example", access_token: "string_example" );
⚙️ Parameters
username: string
access_token: string
🔄 Return
🌐 Endpoint
/integrations/github
POST
carbon.integrations.syncGitbook
You can sync upto 20 Gitbook spaces at a time using this endpoint. Additional parameters below can be used to associate data with the synced pages or modify the sync behavior.
🛠️ Usage
$result = $carbon->integrations->syncGitbook( space_ids: [ "string_example" ], data_source_id: 1, tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, request_id: "string_example" );
⚙️ Parameters
space_ids: string
[]
data_source_id: int
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
request_id: string
🔄 Return
object
🌐 Endpoint
/integrations/gitbook/sync
POST
carbon.integrations.syncGmail
Once you have successfully connected your gmail account, you can choose which emails to sync with us using the filters parameter. Filters is a JSON object with key value pairs. It also supports AND and OR operations. For now, we support a limited set of keys listed below.
label: Inbuilt Gmail labels, for example "Important" or a custom label you created.
after or before: A date in YYYY/mm/dd format (example 2023/12/31). Gets emails after/before a certain date.
You can also use them in combination to get emails from a certain period.
is: Can have the following values - starred, important, snoozed, and unread
Using keys or values outside of the specified values can lead to unexpected behaviour.
An example of a basic query with filters can be
{ "filters": { "key": "label", "value": "Test" } }
Which will list all emails that have the label "Test".
You can use AND and OR operation in the following way:
{ "filters": { "AND": [ { "key": "after", "value": "2024/01/07" }, { "OR": [ { "key": "label", "value": "Personal" }, { "key": "is", "value": "starred" } ] } ] } }
This will return emails after 7th of Jan that are either starred or have the label "Personal". Note that this is the highest level of nesting we support, i.e. you can't add more AND/OR filters within the OR filter in the above example.
🛠️ Usage
$result = $carbon->integrations->syncGmail( filters: [], tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, data_source_id: 1, request_id: "string_example", sync_attachments: False );
⚙️ Parameters
filters: object
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
data_source_id: int
request_id: string
sync_attachments: bool
🔄 Return
🌐 Endpoint
/integrations/gmail/sync
POST
carbon.integrations.syncOutlook
Once you have successfully connected your Outlook account, you can choose which emails to sync with us
using the filters and folder parameter. "folder" should be the folder you want to sync from Outlook. By default
we get messages from your inbox folder.
Filters is a JSON object with key value pairs. It also supports AND and OR operations.
For now, we support a limited set of keys listed below.
category: Custom categories that you created in Outlook.
after or before: A date in YYYY/mm/dd format (example 2023/12/31). Gets emails after/before a certain date. You can also use them in combination to get emails from a certain period.
is: Can have the following values: flagged
An example of a basic query with filters can be
{ "filters": { "key": "category", "value": "Test" } }
Which will list all emails that have the category "Test".
Specifying a custom folder in the same query
{ "folder": "Folder Name", "filters": { "key": "category", "value": "Test" } }
You can use AND and OR operation in the following way:
{ "filters": { "AND": [ { "key": "after", "value": "2024/01/07" }, { "OR": [ { "key": "category", "value": "Personal" }, { "key": "category", "value": "Test" }, ] } ] } }
This will return emails after 7th of Jan that have either Personal or Test as category. Note that this is the highest level of nesting we support, i.e. you can't add more AND/OR filters within the OR filter in the above example.
🛠️ Usage
$result = $carbon->integrations->syncOutlook( filters: [], tags: [], folder: "Inbox", chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, data_source_id: 1, request_id: "string_example", sync_attachments: False );
⚙️ Parameters
filters: object
tags: object
folder: string
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
data_source_id: int
request_id: string
sync_attachments: bool
🔄 Return
🌐 Endpoint
/integrations/outlook/sync
POST
carbon.integrations.syncRssFeed
Rss Feed
🛠️ Usage
$result = $carbon->integrations->syncRssFeed( url: "string_example", tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, request_id: "string_example" );
⚙️ Parameters
url: string
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
request_id: string
🔄 Return
🌐 Endpoint
/integrations/rss_feed
POST
carbon.integrations.syncS3Files
After optionally loading the items via /integrations/items/sync and integrations/items/list, use the bucket name and object key as the ID in this endpoint to sync them into Carbon. Additional parameters below can associate data with the selected items or modify the sync behavior
🛠️ Usage
$result = $carbon->integrations->syncS3Files( ids: [ [ ] ], tags: [], chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, embedding_model: "OPENAI", generate_sparse_vectors: False, prepend_filename_to_chunks: False, max_items_per_chunk: 1, set_page_as_boundary: False, data_source_id: 1, request_id: "string_example", use_ocr: False, parse_pdf_tables_with_ocr: False );
⚙️ Parameters
ids: S3GetFileInput
[]
tags: object
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
embedding_model:
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
max_items_per_chunk: int
Number of objects per chunk. For csv, tsv, xlsx, and json files only.
set_page_as_boundary: bool
data_source_id: int
request_id: string
use_ocr: bool
parse_pdf_tables_with_ocr: bool
🔄 Return
🌐 Endpoint
/integrations/s3/files
POST
carbon.organizations.get
Get Organization
🛠️ Usage
$result = $carbon->organizations->get();
🔄 Return
🌐 Endpoint
/organization
GET
carbon.users.delete
Delete Users
🛠️ Usage
$result = $carbon->users->delete( customer_ids: [ "string_example" ] );
⚙️ Parameters
customer_ids: string
[]
🔄 Return
🌐 Endpoint
/delete_users
POST
carbon.users.get
User Endpoint
🛠️ Usage
$result = $carbon->users->get( customer_id: "string_example" );
⚙️ Parameters
customer_id: string
🔄 Return
🌐 Endpoint
/user
POST
carbon.users.toggleUserFeatures
Toggle User Features
🛠️ Usage
$result = $carbon->users->toggleUserFeatures( configuration_key_name: "string_example", value: [] );
⚙️ Parameters
configuration_key_name: string
value: object
🔄 Return
🌐 Endpoint
/modify_user_configuration
POST
carbon.users.updateUsers
Update Users
🛠️ Usage
$result = $carbon->users->updateUsers( customer_ids: [ "string_example" ], auto_sync_enabled_sources: [ "string_example" ], max_files: -1, max_files_per_upload: -1 );
⚙️ Parameters
customer_ids: string
[]
List of organization supplied user IDs
auto_sync_enabled_sources: AutoSyncEnabledSourcesProperty
max_files: int
Custom file upload limit for the user over all user's files across all uploads. If set, then the user will not be allowed to upload more files than this limit. If not set, or if set to -1, then the user will have no limit.
max_files_per_upload: int
Custom file upload limit for the user across a single upload. If set, then the user will not be allowed to upload more files than this limit in a single upload. If not set, or if set to -1, then the user will have no limit.
🔄 Return
🌐 Endpoint
/update_users
POST
carbon.utilities.fetchUrls
Extracts all URLs from a webpage.
Args: url (str): URL of the webpage
Returns: FetchURLsResponse: A response object with a list of URLs extracted from the webpage and the webpage content.
🛠️ Usage
$result = $carbon->utilities->fetchUrls( url: "url_example" );
⚙️ Parameters
url: string
🔄 Return
🌐 Endpoint
/fetch_urls
GET
carbon.utilities.fetchYoutubeTranscripts
Fetches english transcripts from YouTube videos.
Args: id (str): The ID of the YouTube video. raw (bool): Whether to return the raw transcript or not. Defaults to False.
Returns: dict: A dictionary with the transcript of the YouTube video.
🛠️ Usage
$result = $carbon->utilities->fetchYoutubeTranscripts( id: "id_example", raw: False );
⚙️ Parameters
id: string
raw: bool
🔄 Return
🌐 Endpoint
/fetch_youtube_transcript
GET
carbon.utilities.processSitemap
Retrieves all URLs from a sitemap, which can subsequently be utilized with our web_scrape
endpoint.
🛠️ Usage
$result = $carbon->utilities->processSitemap( url: "url_example" );
⚙️ Parameters
url: string
🔄 Return
object
🌐 Endpoint
/process_sitemap
GET
carbon.utilities.scrapeSitemap
Extracts all URLs from a sitemap and performs a web scrape on each of them.
Args: sitemap_url (str): URL of the sitemap
Returns: dict: A response object with the status of the scraping job message.-->
🛠️ Usage
$result = $carbon->utilities->scrapeSitemap( url: "string_example", tags: [ "key": "string_example", ], max_pages_to_scrape: 1, chunk_size: 1500, chunk_overlap: 20, skip_embedding_generation: False, enable_auto_sync: False, generate_sparse_vectors: False, prepend_filename_to_chunks: False, html_tags_to_skip: [], css_classes_to_skip: [], css_selectors_to_skip: [], embedding_model: "OPENAI" );
⚙️ Parameters
url: string
tags: array<string, Tags1
>
max_pages_to_scrape: int
chunk_size: int
chunk_overlap: int
skip_embedding_generation: bool
enable_auto_sync: bool
generate_sparse_vectors: bool
prepend_filename_to_chunks: bool
html_tags_to_skip: string
[]
css_classes_to_skip: string
[]
css_selectors_to_skip: string
[]
embedding_model:
🔄 Return
object
🌐 Endpoint
/scrape_sitemap
POST
carbon.utilities.scrapeWeb
Conduct a web scrape on a given webpage URL. Our web scraper is fully compatible with JavaScript and supports recursion depth, enabling you to efficiently extract all content from the target website.
🛠️ Usage
$result = $carbon->utilities->scrapeWeb( body: [ [ "url" => "url_example", "recursion_depth" => 3, "max_pages_to_scrape" => 100, "chunk_size" => 1500, "chunk_overlap" => 20, "skip_embedding_generation" => False, "enable_auto_sync" => False, "generate_sparse_vectors" => False, "prepend_filename_to_chunks" => False, "html_tags_to_skip" => [], "css_classes_to_skip" => [], "css_selectors_to_skip" => [], "embedding_model" => "OPENAI", ] ], );
⚙️ Request Body
🔄 Return
object
🌐 Endpoint
/web_scrape
POST
carbon.utilities.searchUrls
Perform a web search and obtain a list of relevant URLs.
As an illustration, when you perform a search for “content related to MRNA,” you will receive a list of links such as the following:
- https://tomrenz.substack.com/p/mrna-and-why-it-matters
- https://www.statnews.com/2020/11/10/the-story-of-mrna-how-a-once-dismissed-idea-became-a-leading-technology-in-the-covid-vaccine-race/
- https://www.statnews.com/2022/11/16/covid-19-vaccines-were-a-success-but-mrna-still-has-a-delivery-problem/
- https://joomi.substack.com/p/were-still-being-misled-about-how
Subsequently, you can submit these links to the web_scrape endpoint in order to retrieve the content of the respective web pages.
Args: query (str): Query to search for
Returns: FetchURLsResponse: A response object with a list of URLs for a given search query.
🛠️ Usage
$result = $carbon->utilities->searchUrls( query: "query_example" );
⚙️ Parameters
query: string
🔄 Return
🌐 Endpoint
/search_urls
GET
carbon.webhooks.addUrl
Add Webhook Url
🛠️ Usage
$result = $carbon->webhooks->addUrl( url: "string_example" );
⚙️ Parameters
url: string
🔄 Return
🌐 Endpoint
/add_webhook
POST
carbon.webhooks.deleteUrl
Delete Webhook Url
🛠️ Usage
$result = $carbon->webhooks->deleteUrl( webhook_id: 1 );
⚙️ Parameters
webhook_id: int
🔄 Return
🌐 Endpoint
/delete_webhook/{webhook_id}
DELETE
carbon.webhooks.urls
Webhook Urls
🛠️ Usage
$result = $carbon->webhooks->urls( pagination: [ "limit" => 10, "offset" => 0, ], order_by: "created_at", order_dir: "desc", filters: [ "ids" => [], ] );
⚙️ Parameters
pagination: Pagination
order_by:
order_dir:
filters: WebhookFilters
🔄 Return
🌐 Endpoint
/webhooks
POST
Author
This PHP package is automatically generated by Konfig