Ingestion Service API

The Ingestion Service manages ingestion sources, which are configurations for connecting to email providers and importing emails.

Endpoints

All endpoints in this service require authentication.

POST /api/v1/ingestion

Creates a new ingestion source.

Access: Authenticated

Request Body

The request body should be a CreateIngestionSourceDto object.

interface CreateIngestionSourceDto {
    name: string;
    provider: 'google' | 'microsoft' | 'generic_imap';
    providerConfig: IngestionCredentials;
}

Responses

• 201 Created: The newly created ingestion source.
• 500 Internal Server Error: An unexpected error occurred.

GET /api/v1/ingestion

Retrieves all ingestion sources.

Access: Authenticated

Responses

• 200 OK: An array of ingestion source objects.
• 500 Internal Server Error: An unexpected error occurred.

GET /api/v1/ingestion/:id

Retrieves a single ingestion source by its ID.

Access: Authenticated

URL Parameters

Parameter	Type	Description
id	string	The ID of the ingestion source.

Responses

• 200 OK: The ingestion source object.
• 404 Not Found: Ingestion source not found.
• 500 Internal Server Error: An unexpected error occurred.

PUT /api/v1/ingestion/:id

Updates an existing ingestion source.

Access: Authenticated

URL Parameters

Parameter	Type	Description
id	string	The ID of the ingestion source.

Request Body

The request body should be an UpdateIngestionSourceDto object.

interface UpdateIngestionSourceDto {
    name?: string;
    provider?: 'google' | 'microsoft' | 'generic_imap';
    providerConfig?: IngestionCredentials;
    status?:
        | 'pending_auth'
        | 'auth_success'
        | 'importing'
        | 'active'
        | 'paused'
        | 'error';
}

Responses

• 200 OK: The updated ingestion source object.
• 404 Not Found: Ingestion source not found.
• 500 Internal Server Error: An unexpected error occurred.

DELETE /api/v1/ingestion/:id

Deletes an ingestion source and all associated data.

Access: Authenticated

URL Parameters

Parameter	Type	Description
id	string	The ID of the ingestion source.

Responses

• 204 No Content: The ingestion source was deleted successfully.
• 404 Not Found: Ingestion source not found.
• 500 Internal Server Error: An unexpected error occurred.

POST /api/v1/ingestion/:id/import

Triggers the initial import process for an ingestion source.

Access: Authenticated

URL Parameters

Parameter	Type	Description
id	string	The ID of the ingestion source.

Responses

• 202 Accepted: The initial import was triggered successfully.
• 404 Not Found: Ingestion source not found.
• 500 Internal Server Error: An unexpected error occurred.

POST /api/v1/ingestion/:id/pause

Pauses an active ingestion source.

Access: Authenticated

URL Parameters

Parameter	Type	Description
id	string	The ID of the ingestion source.

Responses

• 200 OK: The updated ingestion source object with a paused status.
• 404 Not Found: Ingestion source not found.
• 500 Internal Server Error: An unexpected error occurred.

POST /api/v1/ingestion/:id/sync

Triggers a forced synchronization for an ingestion source.

Access: Authenticated

URL Parameters

Parameter	Type	Description
id	string	The ID of the ingestion source.

Responses

• 202 Accepted: The force sync was triggered successfully.
• 404 Not Found: Ingestion source not found.
• 500 Internal Server Error: An unexpected error occurred.