Skip to main content
API docs by Redocly

Knowledge Box & Zone REST API (v1)

API documentation for managing Knowledge Boxes, NUA keys, and API Keys within designated zones.

Knowledge Boxes

Operations for creating, reading, updating, and deleting Knowledge Boxes.

Get Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "slug": "string",
  • "account_id": "string",
  • "zone": "string",
  • "title": "string",
  • "description": "string",
  • "state": "PUBLISHED",
  • "created": "2019-08-24T14:15:22Z",
  • "admin": true,
  • "contrib": true,
  • "allowed_origins": [
    ],
  • "allowed_ip_addresses": [
    ],
  • "search_configs": { },
  • "external_index_provider": "string"
}

Modify Knowledge Box

Modifies an existing Knowledge Box.

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
required
Slug (string) or Slug (null) (Slug)
Title (string) or Title (null) (Title)
KbState (string) or null
Description (string) or Description (null) (Description)
Array of Allowed Origins (strings) or Allowed Origins (null) (Allowed Origins)
Array of Allowed Ip Addresses (strings) or Allowed Ip Addresses (null) (Allowed Ip Addresses)
Search Configs (object) or Search Configs (null) (Search Configs)

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "title": "string",
  • "state": "PUBLISHED",
  • "description": "string",
  • "allowed_origins": [
    ],
  • "allowed_ip_addresses": [
    ],
  • "search_configs": { }
}

Response samples

Content type
application/json
{ }

Delete Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Create Ephemeral Token

Create an ephemeral token to access the Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
Any of
"ephemeral" (string) or Agent Session (string) or Agent Session (null) (Agent Session)
Ttl (integer) or Ttl (null) (Ttl)

Responses

Request samples

Content type
application/json
Example
{
  • "agent_session": "ephemeral",
  • "ttl": 0
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Download Logo

Knowledge Box logo

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Knowledge Box Permissions

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
{
  • "permissions": [
    ]
}

List Knowledge Boxes

List all region Knowledge Boxes that belongs to an specific account that the authenticated user can see

path Parameters
account_id
required
string <uuid> (Account Id)
query Parameters
mode
string (Mode)
Default: "kb"
Enum: "kb" "agent" "agent_no_memory" "agents"

Optional mode filter. 'kb' for standard KBs, 'agent' for agents with memory, 'agent_no_memory' for agents without memory, 'agents' for all agent types (agent + agent_no_memory). Defaults to 'kb'.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Knowledge Box

Creates a new Knowledge Box. The accepted values for the learning_configuration are dynamic and may be dependant of the account used. Accepted field values needs to be checked on the 'Learning configuration schema' endpoint

path Parameters
account_id
required
string <uuid> (Account Id)
Request Body schema: application/json
required
slug
required
string (Slug) ^[a-z0-9_-]+$
title
required
string (Title) non-empty
Description (string) or Description (null) (Description)
mode
string (KBMode)
Default: "kb"
Enum: "kb" "agent" "agent_no_memory"

Mode of the Knowledge Box (immutable after creation). 'kb': Standard KB with NucliaDB storage. 'agent': Agent with memory backed by NucliaDB. 'agent_no_memory': Agent without memory (no NucliaDB KB created).

object (Learning Configuration)
Array of Allowed Origins (strings) or Allowed Origins (null) (Allowed Origins)
Array of Allowed Ip Addresses (strings) or Allowed Ip Addresses (null) (Allowed Ip Addresses)
DummyKBIndexProvider (object) or External index provider (null) (External index provider)

External index provider configuration for the Knowledge Box. If not set, the default NucliaDB's index will be used.

object (Search Configs)
Default: {}

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "title": "string",
  • "description": "string",
  • "mode": "kb",
  • "learning_configuration": { },
  • "allowed_origins": [
    ],
  • "allowed_ip_addresses": [
    ],
  • "external_index_provider": {
    },
  • "search_configs": { }
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Create Ephemeral Token From Sa

Create an ephemeral token to access the Knowledge Box using a Service Account

Request Body schema: application/json
required
"ephemeral" (string) or Agent Session (string) or Agent Session (null) (Agent Session)
Ttl (integer) or Ttl (null) (Ttl)

Responses

Request samples

Content type
application/json
{
  • "agent_session": "ephemeral",
  • "ttl": 0
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Users

Management of users assigned to a Knowledge Box.

Users

List of users of a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
query Parameters
include_user_detail
boolean (Include User Detail)
Default: false

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Users

Assign or remove users from a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
required
Array of Add (objects) or Add (null) (Add)
Array of Update (objects) or Update (null) (Update)
Array of Delete (strings) or Delete (null) (Delete)

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "update": [
    ],
  • "delete": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Invites

Handling Knowledge Box invitation management.

Invite To Knowledge Box

Send an invitation to join a Knowledge Box via email.

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
required
email
required
string <email> (Email)
role
required
string (KbRole)
Enum: "SOWNER" "SMEMBER" "SCONTRIBUTOR"

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "role": "SOWNER"
}

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Invite

Invalidate an invite to join a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
query Parameters
email
required
string <email> (Email)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Invited Users

List of users invited to a Knowledge Box, but not yet joined

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

API Keys

Management of API keys assigned to a Knowledge Box.

Delete Service Account

Delete a new Service Account for a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
sa_id
required
string <uuid> (Sa Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Delete Api Key

Delete an API Key of a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
sa_id
required
string <uuid> (Sa Id)
sa_key_id
required
string <uuid> (Sa Key Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Add Service Account Key

Create an API Key for a Service Account of a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
sa_id
required
string <uuid> (Sa Id)
Request Body schema: application/json
required
expires
required
string <date-time> (Expires)

Responses

Request samples

Content type
application/json
{
  • "expires": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "token": "string"
}

List Service Accounts

List of Service Accounts of a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Service Account

Create a new Service Account for a Knowledge Box

path Parameters
account_id
required
string <uuid> (Account Id)
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
required
title
required
string (Title) non-empty
role
required
string (KbRole)
Enum: "SOWNER" "SMEMBER" "SCONTRIBUTOR"

Responses

Request samples

Content type
application/json
{
  • "title": "string",
  • "role": "SOWNER"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Create Temporal Agent Key

Creates a temporal key to use an agent session

Request Body schema: application/json
required
agent_session
required
string (Agent Session)
ttl
integer (Ttl) [ 1 .. 10 ]
Default: 10

Responses

Request samples

Content type
application/json
{
  • "agent_session": "string",
  • "ttl": 10
}

Response samples

Content type
application/json
{
  • "token": "string"
}

Create Temporal Secure Token

Creates a temporal key for a service account.

The key accepts

Request Body schema: application/json
Any of
ttl
integer (Ttl) [ 1 .. 10 ]
Default: 10
Array of Security Groups (strings) or Security Groups (null) (Security Groups)

Responses

Request samples

Content type
application/json
Example
{
  • "ttl": 10,
  • "security_groups": [
    ]
}

Response samples

Content type
application/json
{
  • "token": "string"
}

NUA Keys

Management of NUA keys.

Delete Nua Client By Id

Deletes an existing Nuclia Understanding API client

path Parameters
account_id
required
string <uuid> (Account Id)
client_id
required
string (Client Id) ^[a-z0-9_-]+$

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Nua Client By Id

Gets the metadata of an existing Nuclia Understanding API

path Parameters
account_id
required
string <uuid> (Account Id)
client_id
required
string (Client Id) ^[a-z0-9_-]+$

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "description": "",
  • "contact": "string",
  • "created": "2019-08-24T14:15:22Z",
  • "partitions": 0,
  • "client_id": "string",
  • "account_id": "string",
  • "processing_webhook": {
    }
}

Set Account Nua Client Key

Recreates a new session key for an existing Nuclia Understanding API client

path Parameters
account_id
required
string <uuid> (Account Id)
client_id
required
string (Client Id) ^[a-z0-9_-]+$

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "client_id": "string"
}

Get Account Nua Clients

Gets the list of Nuclia Understanding API clients of an account

path Parameters
account_id
required
string <uuid> (Account Id)
query Parameters
Client Id (string) or Client Id (null) (Client Id)

Responses

Response samples

Content type
application/json
{
  • "clients": [
    ]
}

Create Account Nua Client

Create a new Nuclia Understanding API client for an account

path Parameters
account_id
required
string <uuid> (Account Id)
Request Body schema: application/json
required
contact
required
string (Contact)
title
required
string (Title) non-empty
Description (string) or Description (null) (Description)
Default: ""
Client Id (string) or Client Id (null) (Client Id)
ProcessingWebhook (object) or null
allow_kb_management
boolean (Allow Kb Management)
Default: false

Responses

Request samples

Content type
application/json
{
  • "contact": "string",
  • "title": "string",
  • "description": "",
  • "client_id": "string",
  • "processing_webhook": {
    },
  • "allow_kb_management": false
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "client_id": "string"
}

Knowledgebox activity

Management of Activity logs for a Knowledge Box.

Get Download Status

Get the status of a download request by Knowledgebox ID and request ID

path Parameters
kb_id
required
string (Kb Id)
request_id
required
string <uuid1> (Request Id)

Responses

Response samples

Content type
application/json
{
  • "request_id": "string",
  • "download_type": "query",
  • "download_format": "ndjson",
  • "event_type": "visited",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "kb_id": "string",
  • "download_url": "string"
}

Activity Logs Metrics

Get metrics for search and ask logs

path Parameters
kb_id
required
string (Kb Id)
query Parameters
aggregation
string (Aggregation)
Default: "millennium"
Enum: "hour" "day" "week" "month" "quarter" "year" "millennium"
from
required
string <date-time> (From)
To (string) or To (null) (To)
Default: "2026-02-27T09:26:54.588433"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Knowledgebox Activity Downloads List

Get the list of monthly activity audit files available to download

path Parameters
kb_id
required
string (Kb Id)
event_type
required
string (EventType)
Enum: "visited" "modified" "deleted" "new" "search" "suggest" "indexed" "chat" "ask" "retrieve" "augment" "started" "stopped" "processed"

Responses

Response samples

Content type
application/json
{
  • "downloads": [
    ]
}

Query Knowledgebox Activity Logs

Query Knowledgebox Activity Logs

path Parameters
kb_id
required
string (Kb Id)
event_type
required
string (EventType)
Enum: "visited" "modified" "deleted" "new" "search" "suggest" "indexed" "chat" "ask" "retrieve" "augment" "started" "stopped" "processed"
Request Body schema: application/json
required
Any of
object (Pagination)
Default: {"limit":10}
year_month
required
string (Year Month)
Array of Show (strings) or "all" (string) (Show)
Default: ["id","date"]
required
object (QueryFiltersCommon)

Responses

Request samples

Content type
application/json
Example
{
  • "pagination": {
    },
  • "year_month": "string",
  • "show": [
    ],
  • "filters": {
    }
}

Response samples

Content type
application/x-ndjson
"{\"question\":null,\"id\":0,\"date\":null,\"user_id\":null,\"user_type\":null,\"client_type\":null,\"total_duration\":null,\"audit_metadata\":null,\"resource_id\":null,\"nuclia_tokens\":null,\"token_details\":null,\"rephrased_question\":null,\"answer\":null,\"learning_id\":null,\"retrieved_context\":null,\"chat_history\":null,\"feedback_good\":null,\"feedback_comment\":null,\"feedback_good_all\":null,\"feedback_good_any\":null,\"feedback\":null,\"model\":null,\"rag_strategies_names\":null,\"rag_strategies\":null,\"status\":null,\"generative_answer_first_chunk_time\":null,\"generative_reasoning_first_chunk_time\":null,\"generative_answer_time\":null,\"remi_scores\":null,\"user_request\":null,\"reasoning\":null,\"resources_count\":null,\"filter\":null,\"retrieval_rephrased_question\":null,\"vectorset\":null,\"security\":null,\"min_score_bm25\":null,\"min_score_semantic\":null,\"result_per_page\":null,\"retrieval_time\":null}\n"

Request The Preparation Of Knowledgebox Activity Logs Download

Request Knowledgebox Activity Logs download

path Parameters
kb_id
required
string (Kb Id)
event_type
required
string (EventType)
Enum: "visited" "modified" "deleted" "new" "search" "suggest" "indexed" "chat" "ask" "retrieve" "augment" "started" "stopped" "processed"
header Parameters
accept
required
string (Accept)
Enum: "application/x-ndjson" "text/csv"
Request Body schema: application/json
required
Any of
year_month
required
string (Year Month)
Array of Show (strings) or "all" (string) (Show)
Default: ["id","date"]
required
object (QueryFiltersCommon)
Email Address (string) or Email Address (null) (Email Address)
notify_via_email
boolean (Notify Via Email)
Default: false

Responses

Request samples

Content type
application/json
Example
{
  • "year_month": "string",
  • "show": [
    ],
  • "filters": {
    },
  • "email_address": "user@example.com",
  • "notify_via_email": false
}

Response samples

Content type
application/json
{
  • "request_id": "string",
  • "download_type": "query",
  • "download_format": "ndjson",
  • "event_type": "visited",
  • "requested_at": "2019-08-24T14:15:22Z",
  • "kb_id": "string",
  • "download_url": "string"
}

Get A Rag Request With Related Remi Scores And Full Context

Get a rag request with full context and REMI scores. Intended for obtaining complete context for an item originating from a /remi/query

path Parameters
kb_uuid
required
string (Kb Uuid)
event_id
required
integer (Event Id)

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "question": "string",
  • "answer": "string",
  • "remi": {
    },
  • "context": [
    ]
}

Query Rag Requests By Scores

Get a list of rag request that matches a remi scores query

path Parameters
kb_uuid
required
string (Kb Uuid)
Request Body schema: application/json
required
ContextRelevanceQuery (object) or null
month
required
string (Month)
Feedback Good (boolean) or Feedback Good (null) (Feedback Good)
Status (string) or null
object (Pagination)
Default: {"limit":10}

Responses

Request samples

Content type
application/json
{
  • "context_relevance": {
    },
  • "month": "string",
  • "feedback_good": true,
  • "status": "SUCCESS",
  • "pagination": {
    }
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": true
}

Aggregated Remi Scores Across Time

Get the evolution of remi scores of a kb on a period of time

path Parameters
kb_uuid
required
string (Kb Uuid)
query Parameters
aggregation
string (Aggregation)
Default: "millennium"
Enum: "hour" "day" "week" "month" "quarter" "year" "millennium"
from
required
string <date-time> (From)
To (string) or To (null) (To)
Default: "2026-02-27T09:26:54.594276"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Backups

Management of Backups for a Knowledge Box.

Delete

Delete knowledgebox backup

path Parameters
account_id
required
string (Account Id)
backup_id
required
string (Backup Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Restore

Restore a backup into a new knowledgebox

path Parameters
account_id
required
string (Account Id)
backup_id
required
string (Backup Id)
Request Body schema: application/json
required
slug
required
string (Slug) ^[a-z0-9_-]+$

The slug of the new restored knowledgebox.

title
required
string (Title)

The title of the new restored knowledgebox.

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

Create

Create knowledgebox backup

path Parameters
account_id
required
string (Account Id)
Request Body schema: application/json
required
kb_id
required
string <uuid4> (Kb Id)

The unique identifier of the knowledgebox to backup.

Responses

Request samples

Content type
application/json
{
  • "kb_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}

List

Get all backups from an account in a region

path Parameters
account_id
required
string (Account Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

External Connections

Get External Connection

path Parameters
kb_id
required
string <uuid> (Kb Id)
connection_id
required
string <uuid> (Connection Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "kb_id": "999c0e19-1947-4a4f-b165-815dc3353cfe",
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "provider": "google_oauth",
  • "capabilities": {
    }
}

Delete External Connection

path Parameters
kb_id
required
string <uuid> (Kb Id)
connection_id
required
string <uuid> (Connection Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Browse Storage

Browse cloud storage to discover sites, drives and folders.

Use this endpoint to help users select a drive and folder path when creating a sync configuration.

SharePoint/OneDrive flow (OAuth):

  1. Resolve site URL: use the /resolve_site endpoint with a site URL → get site_id
  2. List drives in a site: provide site_id → returns drives for that site
    • Use site_id=me for personal OneDrive (OAuth only)
  3. List folders in a drive: provide drive_id → returns folders at root
  4. Navigate folders: provide drive_id and path → returns subfolders

SharePoint flow (certificate auth):

  1. List sites: no parameters → returns all sites (max 50)
    • Or use site_search to search for specific sites
  2. List drives in a site: provide site_id → returns drives for that site
  3. List folders in a drive: provide drive_id → returns folders at root
  4. Navigate folders: provide drive_id and path → returns subfolders

Google Drive flow:

  1. List drives: no parameters → returns My Drive and Shared Drives
  2. List folders: provide drive_id and optionally path

AWS S3 flow:

  1. List buckets: no parameters → returns available buckets
  2. List folders: provide drive_id (bucket name) and optionally path (prefix)

ShareFile flow:

  1. List roots: no parameters → returns root folders
  2. List folders: provide drive_id and optionally path

Dropbox flow:

  1. List root folders: no parameters → returns folders at the Dropbox root
  2. Navigate folders: provide path (e.g. /Documents) → returns subfolders
  • Dropbox does not have drives. Do not pass drive_id.

Parameter validation:

  • site_search cannot be combined with site_id, drive_id, or path
  • site_search is only supported for certificate auth connections (not OAuth)
  • site_id is only valid for SharePoint/Azure connections
  • SharePoint OAuth connections require site_id to browse (use /resolve_site to get it)
  • When drive_id is provided, site_id is ignored (drive_id is sufficient)
path Parameters
kb_id
required
string <uuid> (Kb Id)
connection_id
required
string <uuid> (Connection Id)
query Parameters
Site Search (string) or Site Search (null) (Site Search)

Search query for SharePoint sites. Only supported for certificate auth connections. For OAuth, use the /resolve_site endpoint instead.

Site Id (string) or Site Id (null) (Site Id)

Site ID to list drives for. Use 'me' for personal OneDrive (OAuth only).

Drive Id (string) or Drive Id (null) (Drive Id)

Drive ID to browse folders in.

Path (string) or Path (null) (Path)

Folder path to list within the drive.

Page Token (string) or Page Token (null) (Page Token)

Pagination token

Responses

Response samples

Content type
application/json
{
  • "sites": [
    ],
  • "drives": [
    ],
  • "folders": [
    ],
  • "next_page_token": "string"
}

Resolve Site

Resolve a SharePoint site URL to its site ID.

Given a full SharePoint site URL, this endpoint returns the site ID, name, and web URL. The returned site ID can then be used with the /browse endpoint to list drives for that site.

This endpoint works with the Sites.Selected permission scope, as long as the specific site has been granted access to the application.

Usage flow:

  1. Call this endpoint with a site URL → get site_id
  2. Call /browse?site_id={site_id} → get drives
  3. Call /browse?drive_id={drive_id} → get folders
path Parameters
kb_id
required
string <uuid> (Kb Id)
connection_id
required
string <uuid> (Connection Id)
query Parameters
site_url
required
string (Site Url)

Full SharePoint site URL to resolve. Example: https://contoso.sharepoint.com/sites/TeamSite

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "web_url": "string"
}

List External Connections

path Parameters
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create External Connection

Create an external connection for cloud storage sync.

For OAuth providers (google_oauth, azure_oauth, sharefile_oauth):

  • Only provider is required in the request body
  • Returns an authorize_url that the user should visit to complete the OAuth flow
  • After successful authorization, an ExternalConnection will be created
  • Returns HTTP 200

For aws_s3_assume_role:

  • Both provider and credentials are required in the request body
  • Returns the created ExternalConnection directly
  • Returns HTTP 201
path Parameters
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
required
provider
required
string (Provider)
Enum: "google_oauth" "azure_oauth" "azure_certificate_credentials" "aws_s3_assume_role" "sharefile_oauth" "dropbox_oauth"
AWSS3AssumeRoleCredentials (object) or AzureCertificateCredentials (object) or Credentials (null) (Credentials)

Responses

Request samples

Content type
application/json
{
  • "provider": "google_oauth",
  • "credentials": {
    }
}

Response samples

Content type
application/json
Example
{
  • "authorize_url": "string"
}

Get S3 Assume Role Info

Returns the AWS assume-role information that a client needs to create an IAM role in their own AWS account for cross-account S3 access. The client should use the returned external_id, role_name, and aws_account_id to configure the IAM role trust policy.

path Parameters
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
{
  • "external_id": "string",
  • "role_name": "string",
  • "aws_account_id": "string"
}

Sync Configs

Get Config

path Parameters
kb_id
required
string <uuid> (Kb Id)
config_id
required
string <uuid> (Config Id)

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "kb_id": "999c0e19-1947-4a4f-b165-815dc3353cfe",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "sync_root_path": "string",
  • "sync_interval_minutes": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "external_connection": {
    },
  • "drive_id": "string",
  • "last_sync_run": "2019-08-24T14:15:22Z"
}

Delete Config

path Parameters
kb_id
required
string <uuid> (Kb Id)
config_id
required
string <uuid> (Config Id)

Responses

Response samples

Content type
application/json
{
  • "detail": [
    ]
}

Get Authorize Url

path Parameters
kb_id
required
string <uuid> (Kb Id)
config_id
required
string <uuid> (Config Id)
Request Body schema: application/json
required
Widget Redirect Url (string) or Widget Redirect Url (null) (Widget Redirect Url)
rao_redirect_url
required
string (Rao Redirect Url)

Responses

Request samples

Content type
application/json
{
  • "widget_redirect_url": "string",
  • "rao_redirect_url": "string"
}

Response samples

Content type
application/json
{
  • "authorize_url": "string"
}

Validate Resources

Validate that the user has read access to the specified resources.

This endpoint checks if the provided credentials have access to the files/items specified in the request. The provider is determined from the sync config. Credentials must be encrypted using the same encryption key used for external connections.

Args: kb_id: The knowledge base ID. config_id: The sync config ID (determines the provider). item: The validation input containing encrypted credentials and resources to validate.

Returns: ResourceValidationOutput with lists of valid and invalid resources.

path Parameters
kb_id
required
string <uuid> (Kb Id)
config_id
required
string <uuid> (Config Id)
Request Body schema: application/json
required
required
object (Credentials)
required
Array of GoogleDriveResourceIdentifier (object) or SharePointResourceIdentifier (object) or S3ResourceIdentifier (object) or ShareFileResourceIdentifier (object) or DropboxResourceIdentifier (object) (Resources)

Responses

Request samples

Content type
application/json
{
  • "credentials": { },
  • "resources": [
    ]
}

Response samples

Content type
application/json
{
  • "valid_resources": [
    ],
  • "invalid_resources": [
    ]
}

List Configs

path Parameters
kb_id
required
string <uuid> (Kb Id)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Config

path Parameters
kb_id
required
string <uuid> (Kb Id)
Request Body schema: application/json
required
name
required
string (Name)
sync_root_path
required
string (Sync Root Path)
external_connection_id
required
string <uuid> (External Connection Id)
Drive Id (string) or Drive Id (null) (Drive Id)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "sync_root_path": "string",
  • "external_connection_id": "02487ec4-86a5-4d8b-a68d-9ad194251584",
  • "drive_id": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "kb_id": "999c0e19-1947-4a4f-b165-815dc3353cfe",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "sync_root_path": "string",
  • "sync_interval_minutes": 0,
  • "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4",
  • "external_connection": {
    },
  • "drive_id": "string",
  • "last_sync_run": "2019-08-24T14:15:22Z"
}

Sync Jobs

List Jobs

List sync jobs for a sync config with cursor-based pagination.

Use the next_cursor from the response to fetch the next page of results.

path Parameters
kb_id
required
string <uuid> (Kb Id)
config_id
required
string <uuid> (Config Id)
query Parameters
limit
integer (Limit) [ 1 .. 100 ]
Default: 20

Maximum number of jobs to return (1-100)

Cursor (string) or Cursor (null) (Cursor)

Pagination cursor from previous response to fetch next page

order
string (SortOrder)
Default: "desc"
Enum: "asc" "desc"

Sort order by creation time: 'desc' (newest first) or 'asc' (oldest first)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Trigger Sync

Trigger an immediate sync for a sync config.

Creates a new pending sync job that will be processed by the sync job runner. Returns 409 Conflict if there's already an active (pending or in-progress) job for the specified config.

Args: data: Optional input. Set options.full_sync=True to ignore incremental sync state and perform a full re-sync. Note: S3 and ShareFile providers always perform full syncs as they don't support delta tracking.

path Parameters
kb_id
required
string <uuid> (Kb Id)
config_id
required
string <uuid> (Config Id)
Request Body schema: application/json
Any of
full_sync
boolean (Full Sync)
Default: false

If True, ignore incremental sync state and perform a full sync. Note: S3 and ShareFile providers always perform full syncs as they don't support delta tracking.

Responses

Request samples

Content type
application/json
Example
{
  • "full_sync": false
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "created_at": "2019-08-24T14:15:22Z",
  • "finished_at": "2019-08-24T14:15:22Z",
  • "config_id": "d1d31429-d888-4f1c-b9c1-4e842f9bce5b",
  • "status": "pending",
  • "options": {
    }
}

Get Job Logs

Get logs for a sync job with cursor-based pagination.

Use the next_cursor from the response to fetch the next page of results.

Supports optional filtering by:

  • level: Log level (DEBUG, INFO, WARNING, ERROR, EXCEPTION, CRITICAL)
  • start_date / end_date: Timestamp range
path Parameters
kb_id
required
string <uuid> (Kb Id)
job_id
required
string <uuid> (Job Id)
query Parameters
limit
integer (Limit) [ 1 .. 500 ]
Default: 50

Maximum number of log entries to return (1-500)

Cursor (integer) or Cursor (null) (Cursor)

ID-based cursor from previous response to fetch next page (logs with id < cursor)

LogLevel (string) or Level (null) (Level)

Filter by log level

Start Date (string) or Start Date (null) (Start Date)

Filter logs with timestamp >= start_date (ISO 8601 format)

End Date (string) or End Date (null) (End Date)

Filter logs with timestamp <= end_date (ISO 8601 format)

order
string (SortOrder)
Default: "desc"
Enum: "asc" "desc"

Sort order by ID: 'desc' (newest first) or 'asc' (oldest first)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": 0
}