Call the FORGE VESPER Importer Endpoints

API endpoints

All endpoints in this section require the configured API key header. They are also accessible via the Swagger UI, available at {baseURL}/swagger.

Import a CSV file

Uploads a CSV file containing a list of VODS, PLAYLISTS, SEASONS, SERIES or BUCKETS and creates a file import record.

POST /api/csv
Content-Type: multipart/form-data
x-api-key: <shared-secret>

Form data:

Field	Type	Description
file	CSV file	Non-empty .csv file with content type text/csv or application/csv.

Response:

• 202 Accepted: the file was accepted and queued for background ingestion.
• 400 Bad Request: validation failed, for example the upload is missing, empty, not a CSV file, or exceeds the configured request size.
• 401 Unauthorized: missing or invalid shared secret.

Successful response body:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "fileName": "vods.csv",
  "type": "Vod",
  "createdAt": "2026-01-01T12:00:00Z"
}

The Location header of the response points to GET /api/csv/{id}. This ID can be used to check the processing status of the file (see below).

info

• Re-uploading a file with the same filename updates the existing file record because source files are upserted by filename using a case-insensitive unique index.
• Re-importing an older entity event does not overwrite a newer staged entity because staging upserts compare event timestamps.

Check a file import status by ID

Returns the current processing status of an uploaded file.

GET /api/csv/{id}
x-api-key: <shared-secret>

Route parameters:

Parameter	Type	Description
id	GUID	Import ID returned by POST /api/csv.

Response:

• 200 OK: file import status found.
• 401 Unauthorized: missing or invalid shared secret.
• 404 Not Found: no file import exists for the requested ID.

Successful response body:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "fileName": "vods.csv",
  "type": "Vod",
  "status": "Completed",
  "createdAt": "2026-01-01T12:00:00Z",
  "lastUpdatedAt": "2026-01-01T12:00:10Z",
  "errorMessage": null
}

File status values are:

Status	Meaning
New	The upload has been accepted and is waiting for the ingestion worker.
Processing	The ingestion worker is processing the file, or processing failed and stored an error message.
Completed	The file was parsed and staged successfully.
Failed	Defined by the model but not currently set by the ingestion worker.

If Status is Failed, the errorMessage property will contain details about the exception that was raised.

Check an entity ingestion status by entity ID and type

Returns the staging and notification status for a specific imported entity.

GET /api/{entity-type}/{id}
x-api-key: <shared-secret>

Supported entity routes:

Entity type	Endpoint
VOD	GET /api/vods/{id}
Playlist	GET /api/playlists/{id}
Series	GET /api/series/{id}
Season	GET /api/seasons/{id}
Bucket	GET /api/buckets/{id}

Route parameters:

Parameter	Type	Description
entity-type	Path segment	One of vods, playlists, series, seasons, or buckets.
id	String	Entity identifier stored in the related staging collection.

Response:

• 200 OK: entity status found.
• 401 Unauthorized: missing or invalid shared secret.
• 404 Not Found: no staged entity exists for the requested ID.

Successful response body:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "entityType": "Vod",
  "status": "Completed",
  "staged": true,
  "processed": true,
  "notificationStatus": "Sent"
}

Health and monitoring endpoints

Endpoint	Description
GET /healthz/live	Liveness probe.
GET /healthz/ready	Readiness probe, including MongoDB connectivity.
GET /openapi/v1.json	OpenAPI document.
GET /swagger	Swagger UI.

Notes

• The importer endpoints are protected by the shared-secret API key header.
• The Location header returned from POST /api/csv is the starting point for polling import status by ID.
• Health endpoints are useful for operational readiness and liveness checks in deployment environments.