Ingestion API

Manage ingestion sources — the configured connections to email providers (Google Workspace, Microsoft 365, IMAP, and file imports). Credentials are never returned in responses.

Create an Ingestion Source

Create an ingestion source

POST

/v1/ingestion-sources

Creates a new ingestion source and validates the connection. Returns the created source without credentials. Requires create:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Request Body

application/json

{

  

"name": "Company Google Workspace",

  

"provider": "string",

  

"providerConfig": {

  

}

}

Responses

Ingestion source created successfully.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"name": "Company Google Workspace",

  

"provider": "google_workspace",

  

"status": "active",

  

"createdAt": "string",

  

"updatedAt": "string",

  

"lastSyncStartedAt": "string",

  

"lastSyncFinishedAt": "string",

  

"lastSyncStatusMessage": "string"

}

POST

/v1/ingestion-sources

Playground

Authorization

bearerAuth

Body

Samples

Powered by VitePress OpenAPI

List Ingestion Sources

List ingestion sources

GET

/v1/ingestion-sources

Returns all ingestion sources accessible to the authenticated user. Credentials are excluded from the response. Requires read:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Responses

Array of ingestion sources.

Content-Type

application/json

[

  

{

  

  

"id": "clx1y2z3a0000b4d2",

  

  

"name": "Company Google Workspace",

  

  

"provider": "google_workspace",

  

  

"status": "active",

  

  

"createdAt": "string",

  

  

"updatedAt": "string",

  

  

"lastSyncStartedAt": "string",

  

  

"lastSyncFinishedAt": "string",

  

  

"lastSyncStatusMessage": "string"

  

}

]

GET

/v1/ingestion-sources

Playground

Authorization

bearerAuth

Samples

Powered by VitePress OpenAPI

Get an Ingestion Source

Get an ingestion source

GET

/v1/ingestion-sources/{id}

Returns a single ingestion source by ID. Credentials are excluded. Requires read:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Ingestion source details.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"name": "Company Google Workspace",

  

"provider": "google_workspace",

  

"status": "active",

  

"createdAt": "string",

  

"updatedAt": "string",

  

"lastSyncStartedAt": "string",

  

"lastSyncFinishedAt": "string",

  

"lastSyncStatusMessage": "string"

}

GET

/v1/ingestion-sources/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Update an Ingestion Source

Update an ingestion source

PUT

/v1/ingestion-sources/{id}

Updates configuration for an existing ingestion source. Requires update:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Request Body

application/json

{

  

"name": "string",

  

"provider": "string",

  

"status": "string",

  

"providerConfig": {

  

}

}

Responses

Updated ingestion source.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"name": "Company Google Workspace",

  

"provider": "google_workspace",

  

"status": "active",

  

"createdAt": "string",

  

"updatedAt": "string",

  

"lastSyncStartedAt": "string",

  

"lastSyncFinishedAt": "string",

  

"lastSyncStatusMessage": "string"

}

PUT

/v1/ingestion-sources/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Body

Samples

Powered by VitePress OpenAPI

Delete an Ingestion Source

Delete an ingestion source

DELETE

/v1/ingestion-sources/{id}

Permanently deletes an ingestion source. Deletion must be enabled in system settings. Requires delete:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Ingestion source deleted. No content returned.

DELETE

/v1/ingestion-sources/{id}

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Trigger Initial Import

Trigger initial import

POST

/v1/ingestion-sources/{id}/import

Enqueues an initial import job for the ingestion source. This imports all historical emails. Requires create:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Initial import job accepted and queued.

Content-Type

application/json

{

  

"message": "Operation completed successfully."

}

POST

/v1/ingestion-sources/{id}/import

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Pause an Ingestion Source

Pause an ingestion source

POST

/v1/ingestion-sources/{id}/pause

Sets the ingestion source status to paused, stopping continuous sync. Requires update:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Ingestion source paused. Returns the updated source.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"name": "Company Google Workspace",

  

"provider": "google_workspace",

  

"status": "active",

  

"createdAt": "string",

  

"updatedAt": "string",

  

"lastSyncStartedAt": "string",

  

"lastSyncFinishedAt": "string",

  

"lastSyncStatusMessage": "string"

}

POST

/v1/ingestion-sources/{id}/pause

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Force Sync

Force sync

POST

/v1/ingestion-sources/{id}/sync

Triggers an out-of-schedule continuous sync for the ingestion source. Requires sync:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Example"clx1y2z3a0000b4d2"

Responses

Force sync job accepted and queued.

Content-Type

application/json

{

  

"message": "Operation completed successfully."

}

POST

/v1/ingestion-sources/{id}/sync

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Reindex an Ingestion Source

Rebuilds the search-index documents for a source (and its whole merge group) from the archived emails already in the database — it never re-downloads or re-ingests, and it never creates duplicate documents (Meilisearch is keyed by the email ID, so re-adding upserts). Send {"mode": "full"} to rebuild every document, or omit it (default missing) to only index emails not yet in the index.

Reindex an ingestion source

POST

/v1/ingestion-sources/{id}/reindex

Enqueues a reindex of the source (and its merge group). Rebuilds search documents from existing archived emails without re-ingesting or duplicating. Requires sync:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Request Body

application/json

{

  

"mode": "string"

}

Responses

Reindex job accepted and queued.

POST

/v1/ingestion-sources/{id}/reindex

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Body

Samples

Powered by VitePress OpenAPI

Reindex All Sources

Enqueues a reindex across every ingestion source. Requires manage:ingestion.

Reindex the entire archive

POST

/v1/ingestion-sources/reindex-all

Enqueues a reindex of every ingestion source. Rebuilds search documents from existing archived emails without re-ingesting. Requires manage:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Request Body

application/json

{

  

"mode": "string"

}

Responses

Reindex job accepted and queued.

POST

/v1/ingestion-sources/reindex-all

Playground

Authorization

bearerAuth

Body

Samples

Powered by VitePress OpenAPI

Get Index Health

Compares the number of archived emails in the database against the number of documents in the search index for a source (and its merge group). A gap means some emails are missing from search and can be repaired with a reindex.

Get index health for a source

GET

/v1/ingestion-sources/{id}/index-health

Returns the number of archived emails vs. indexed documents for the source (and its merge group). Requires read:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Responses

Index health snapshot.

Content-Type

application/json

{

  

"archivedCount": 0,

  

"indexedCount": 0

}

GET

/v1/ingestion-sources/{id}/index-health

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Get Statistics

Read-only statistics for a source (and its merge group): email/mailbox/thread counts, storage usage (email + attachment bytes, deduplicated), index coverage, attachment and compliance counts, a per-mailbox breakdown, merge-group children, and recent activity.

Get statistics for a source

GET

/v1/ingestion-sources/{id}/stats

Returns read-only statistics for the source (and its merge group) — email/mailbox/thread counts, storage usage, index coverage, attachment/compliance counts, per-mailbox breakdown, merge-group children, and recent activity. Requires read:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Responses

Ingestion source statistics.

GET

/v1/ingestion-sources/{id}/stats

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI

Unmerge an Ingestion Source

Unmerge a child ingestion source

POST

/v1/ingestion-sources/{id}/unmerge

Detaches a child source from its merge group, making it a standalone root source. Requires update:ingestion permission.

Authorizations

bearerAuth

JWT obtained from POST /v1/auth/login. Pass as Authorization: Bearer <token>.

Type

HTTP (bearer)

or

apiKeyAuth

API key generated via POST /v1/api-keys. Pass as X-API-KEY: <key>.

Type

API Key (header: X-API-KEY)

Parameters

Path Parameters

id*

Type

string

Required

Responses

Source unmerged. Returns the updated source.

Content-Type

application/json

{

  

"id": "clx1y2z3a0000b4d2",

  

"name": "Company Google Workspace",

  

"provider": "google_workspace",

  

"status": "active",

  

"createdAt": "string",

  

"updatedAt": "string",

  

"lastSyncStartedAt": "string",

  

"lastSyncFinishedAt": "string",

  

"lastSyncStatusMessage": "string"

}

POST

/v1/ingestion-sources/{id}/unmerge

Playground

Authorization

bearerAuth

Variables

Key

Value

id*

Samples

Powered by VitePress OpenAPI