PSYKHE AIPSYKHE AI
Ingestion APIAPI v1 ReferenceIngestion

Get ingestion status

Returns the processing status for a previously created ingestion.

GET
/v1/ingestion/{id}

Returns the processing status for a previously created ingestion.

Status is returned as an integer:

  • 1 - UNKNOWN
  • 2 - CREATED (accepted, queued)
  • 3 - STARTED (processing in progress)
  • 4 - COMPLETED (successfully processed)
  • 5 - FAILED (processing failed; check ingestion logs)

Authorization

PrivateApiKeyHeader
X-PSYKHE-API-KEY<token>

Private API key (sk_...). Server-to-server only; never expose in client-side code.

In: header

Path Parameters

id*integer

Ingestion ID returned from POST /ingestion/.

Response Body

application/json

curl -X GET "https://api.psykhe.dev/v1/ingestion/0"
{
  "errors": null,
  "meta": null,
  "data": {
    "id": 477021,
    "client_id": "fwrd-staging",
    "trigger_source": {
      "type": "client",
      "mode": "insert",
      "comment": null,
      "metadata": null,
      "user": null
    },
    "product_metrics": null,
    "file_identifier": "cd0b729438a546e6ef8516de00affb0691f612c0",
    "status": 2,
    "created_at": "2026-05-13T18:03:50.828851Z",
    "updated_at": "2026-05-13T18:03:51.260869Z"
  }
}
Empty
Empty

Create new ingestion POST

Creates a new ingestion job for processing product data. ### Which processing mode should I use? | Scenario | Use this mode | |---|---| | Webhook updates (single product or small batch) | `insert` | | Incremental sync (only changed products) | `insert` | | **Full catalog sync** (you are sending the *entire* active catalog) | `soft_replace` | | Hourly / daily catalog dump | `soft_replace` | Set the mode via the `X-PSYKHE-PROCESSING-MODE` header. - **`insert` (default)** - Upserts products present in the feed. Products *not* in the feed are left untouched. This is the safe default for webhooks and incremental batches because it never disables anything. - **`soft_replace`** - Upserts products present in the feed *and marks every other active product in your catalog as inactive* (excluded from recommendations; data is preserved, not hard-deleted). Only use this when the payload contains your **complete** catalog. Sending a partial catalog with `soft_replace` will disable every product you omitted. Request body is newline-delimited JSON (JSONL), one product per line. Gzip compression is supported via `Content-Encoding: gzip`. The ingestion is processed asynchronously - the response returns immediately with an `ingestion_id` you can poll via `GET /ingestion/{id}`.