Overview

The Create Ingest URL endpoint allows you to push source data (typically a product feed for use in sponsored listings) directly to Kevel storage using the same authentication as other Kevel APIs. When you create a new ingest URL, we'll give you back a signed URL for an Amazon S3 bucket. That URL can then be used to send files to ItemDB, the service that powers Kevel Catalog.

This endpoint can be used for one-time imports during setup and testing, and for automated syncs built into an ongoing integration. In both cases the workflow is as follows:

1. Make a POST request to /v1/itemdb/ingest-url authenticating with your Kevel API key (params below)
2. Upload your source file to the url returned in #1
3. Check the result by requesting the status link returned in #1 (see Ingest Status)

Signed URLs expire after 1 hour, so you must request a fresh ingest URL each time you wish to upload a new version of your source data.

📘

Completing the Ingestion Setup

Your Kevel account team will guide you through the setup process which includes some internal configuration steps to ensure files received are mapped to the correct Catalog in your network.

File requirements

• Format: NDJSON, with one JSON object per line.
• Encoding: UTF-8. A leading byte order mark (BOM) and blank lines are ignored.
• Compression: gzip, once your Kevel account team has enabled it for your network. Give the file a .gz extension, for example products.ndjson.gz. If compression is not enabled for your network, upload the file uncompressed.
• Unique IDs: each item ID can appear only once in a file. A file that repeats an ID fails to process, and nothing from it is applied.

Frequently asked questions

How do I check the progress of the ingestion?

Request the status link provided with the ingest URL, using your Kevel API key.

curl -X GET \
     -H "X-Kevel-ApiKey:$KEVEL_API_KEY" \
     '{STATUS_URL}'

The response gives the status of your file (not found, incoming, processing, failed or completed) and a log of what happened while it was processed. See Ingest Status for what each status means and how to read the log.

If you receive a failed or not found status, contact your Kevel account team to help identify and fix any issues encountered during ingestion.

Why is my file still incoming?

Kevel picks up files from the folder your account team set up for your network. If a file stays in incoming longer than you expect, check that the folder you sent when creating the ingest URL matches that folder exactly, including any table ID at the end, such as products-103. The endpoint does not check it, and a file uploaded to any other folder is not picked up. If the folder is right, contact your Kevel account team.

Why did my ingestion fail with duplicate IDs?

Each item ID can appear only once in a file. When a file repeats an ID, the ingestion fails and nothing from the file is applied. The Ingest Status log lists the repeated IDs in DuplicateIds. Remove the duplicates, request a fresh ingest URL and upload the file again.

What should I do if I get an authentication error code such as SignatureDoesNotMatch?

If you receive a SignatureDoesNotMatch or other authentication error code when attempting to upload your source file, retry the upload using the --upload-file cURL command shown below via the command line. Note that tools like Postman may not support this method.

curl --request PUT --upload-file products.ndjson.gz '{SIGNED_INGEST_URL}'