7551d4d7c7
* Add agents AI doc * Allow local file path for Mbox file ingestion --------- Co-authored-by: Wei S. <5291640+wayneshn@users.noreply.github.com>
5.0 KiB
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-sources
Creates a new ingestion source.
Access: Authenticated
Request Body
The request body should be a CreateIngestionSourceDto object.
interface CreateIngestionSourceDto {
name: string;
provider: 'google_workspace' | 'microsoft_365' | 'generic_imap' | 'pst_import' | 'eml_import' | 'mbox_import';
providerConfig: IngestionCredentials;
}
Example: Creating an Mbox Import Source with File Upload
{
"name": "My Mbox Import",
"provider": "mbox_import",
"providerConfig": {
"type": "mbox_import",
"uploadedFileName": "emails.mbox",
"uploadedFilePath": "open-archiver/tmp/uuid-emails.mbox"
}
}
Example: Creating an Mbox Import Source with Local File Path
{
"name": "My Mbox Import",
"provider": "mbox_import",
"providerConfig": {
"type": "mbox_import",
"localFilePath": "/path/to/emails.mbox"
}
}
Note: When using localFilePath, the file will not be deleted after import. When using uploadedFilePath (via the upload API), the file will be automatically deleted after import. The same applies to pst_import and eml_import providers.
Responses
- 201 Created: The newly created ingestion source.
- 500 Internal Server Error: An unexpected error occurred.
GET /api/v1/ingestion-sources
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-sources/: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-sources/: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-sources/: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-sources/: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-sources/: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
pausedstatus. - 404 Not Found: Ingestion source not found.
- 500 Internal Server Error: An unexpected error occurred.
POST /api/v1/ingestion-sources/: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.