Appearance
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
JSON "name": "Company Google Workspace", "provider": "string", "providerConfig": { }
{
}
Responses
Ingestion source created successfully.
application/json
JSON "id": "clx1y2z3a0000b4d2", "name": "Company Google Workspace", "provider": "google_workspace", "status": "active", "createdAt": "string", "updatedAt": "string", "lastSyncStartedAt": "string", "lastSyncFinishedAt": "string", "lastSyncStatusMessage": "string"
{
}
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.
application/json
JSON { "id": "clx1y2z3a0000b4d2", "name": "Company Google Workspace", "provider": "google_workspace", "status": "active", "createdAt": "string", "updatedAt": "string", "lastSyncStartedAt": "string", "lastSyncFinishedAt": "string", "lastSyncStatusMessage": "string" }
[
]
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
Requiredstring
Example
"clx1y2z3a0000b4d2"Responses
Ingestion source details.
application/json
JSON "id": "clx1y2z3a0000b4d2", "name": "Company Google Workspace", "provider": "google_workspace", "status": "active", "createdAt": "string", "updatedAt": "string", "lastSyncStartedAt": "string", "lastSyncFinishedAt": "string", "lastSyncStatusMessage": "string"
{
}
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
Requiredstring
Example
"clx1y2z3a0000b4d2"Request Body
application/json
JSON "name": "string", "provider": "string", "status": "string", "providerConfig": { }
{
}
Responses
Updated ingestion source.
application/json
JSON "id": "clx1y2z3a0000b4d2", "name": "Company Google Workspace", "provider": "google_workspace", "status": "active", "createdAt": "string", "updatedAt": "string", "lastSyncStartedAt": "string", "lastSyncFinishedAt": "string", "lastSyncStatusMessage": "string"
{
}
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
Requiredstring
Example
"clx1y2z3a0000b4d2"Responses
Ingestion source deleted. No content returned.
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
Requiredstring
Example
"clx1y2z3a0000b4d2"Responses
Initial import job accepted and queued.
application/json
JSON "message": "Operation completed successfully."
{
}
Start OAuth Mailbox Authorization
Starts (or restarts) the OAuth authorization of an oauth_mailbox source. Serves first-time setup and re-authorization identically.
Start OAuth mailbox authorization
POST
/v1/ingestion-sources/{id}/oauth/authorize
Starts (or restarts) the OAuth authorization of an oauth_mailbox ingestion source. For the authorization code flow the response carries the URL to send the administrator's browser to; for the device code flow it carries the user code and verification URL to display, with the device code itself kept server-side. The same endpoint serves first-time authorization and the Re-authorize action after tokens expire or consent is revoked. 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
Requiredstring
Request Body
application/json
JSON "flow": "string"
{
}
Responses
Authorization started.
application/json
JSON "flow": "string", "authorizationUrl": "string", "userCode": "string", "verificationUri": "string", "verificationUriComplete": "string", "expiresIn": 0, "interval": 0
{
}
Poll a Device-Code Authorization
One poll step of an in-progress device-code authorization. Call on the interval the authorize endpoint returned, until pending is false.
Poll a device-code authorization
POST
/v1/ingestion-sources/{id}/oauth/poll
Performs one poll step of an in-progress device-code authorization for an oauth_mailbox source. The browser calls this on the interval returned by the authorize endpoint until pending is false. On success the source moves to auth_success and its initial import starts. 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
Requiredstring
Responses
Current state of the authorization.
application/json
JSON "pending": true, "status": "string", "interval": 0, "error": "string", "warning": "string"
{
}
OAuth Callback
The browser return leg of the authorization code flow. Unauthenticated — the signed, single-use state parameter is the credential. Not intended to be called directly.
OAuth authorization callback
GET
/v1/oauth/callback
The browser return leg of an OAuth Mailbox authorization (authorization code flow). The identity provider redirects the administrator's browser here with a code and the signed state issued when the authorization started. On success the granted tokens are stored, the source moves to auth_success and its initial import starts; the response is an HTML page that returns the browser to the ingestion sources list. This endpoint is unauthenticated — the signed, single-use state is the credential — and it never exposes tokens.
Parameters
Query Parameters
state*
Type
Requiredstring
code
Type
string
error
Set by the provider when the user declined consent.
Type
string
Responses
HTML page that redirects the browser back to the ingestion sources list, with the outcome in the query string.
text/html
JSON
"string"
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
Requiredstring
Example
"clx1y2z3a0000b4d2"Responses
Ingestion source paused. Returns the updated source.
application/json
JSON "id": "clx1y2z3a0000b4d2", "name": "Company Google Workspace", "provider": "google_workspace", "status": "active", "createdAt": "string", "updatedAt": "string", "lastSyncStartedAt": "string", "lastSyncFinishedAt": "string", "lastSyncStatusMessage": "string"
{
}
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
Requiredstring
Example
"clx1y2z3a0000b4d2"Responses
Force sync job accepted and queued.
application/json
JSON "message": "Operation completed successfully."
{
}
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
Requiredstring
Request Body
application/json
JSON "mode": "string"
{
}
Responses
Reindex job accepted and queued.
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
JSON "mode": "string"
{
}
Responses
Reindex job accepted and queued.
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
Requiredstring
Responses
Index health snapshot.
application/json
JSON "archivedCount": 0, "indexedCount": 0
{
}
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
Requiredstring
Responses
Ingestion source statistics.
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
Requiredstring
Responses
Source unmerged. Returns the updated source.
application/json
JSON "id": "clx1y2z3a0000b4d2", "name": "Company Google Workspace", "provider": "google_workspace", "status": "active", "createdAt": "string", "updatedAt": "string", "lastSyncStartedAt": "string", "lastSyncFinishedAt": "string", "lastSyncStatusMessage": "string"
{
}