# 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](https://dev.kevel.com/docs/catalog).

This endpoint can be used for one-time imports during a setup and testing phase 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

**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.

## Frequently asked questions

### How do I check the progress of the ingestion?

You can check whether your file is queued for processing (incoming), processing, completed or failed by using the `status` link provided with the ingest URL.

```text
curl -X GET \
     -H 'X-Adzerk-ApiKey:$ADZERK_API_KEY' \
     '{STATUS_URL}'
```

You may see the following statuses:

- `not found` File was not successfully uploaded to Kevel storage.
- `incoming` File was successfully uploaded to Kevel storage, but has not yet been processed.
- `processing` File was successfully uploaded to Kevel storage and is currently being processed.
- `failed` File was successfully uploaded to Kevel storage, but processing failed due to an error.
- `completed` File was successfully uploaded to Kevel storage and successfully processed. Any changes to the catalog are now "live" in the system.

Contact your Kevel account team for more details if you receive a `failed` or `not found` status to help identify and fix any issues encountered during the ingestion.

### 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
curl --request PUT --upload-file products.ndjson.gz '{SIGNED_INGEST_URL}'
```

#### Parameters

- **folder** (string, required): The folder or directory where the source file should be uploaded. When using with Kevel Catalog, this is generally `products` or `categories`.
- **filename** (string, required): The name of the file that will be uploaded to the returned URL. This must include a file type extension (eg `products.ndjson.gz`). Note: Kevel will automatically prepend a datetime string to the provided file name.

### Example Response

```json
{
  "url": "https://kevel-prod-itemdb-ingest-default.s3.amazonaws.com/99999/products/incoming/2024-04-12T20%3A02%3A18.425674978-products.ndjson?x-amz-security-token=xxx&AWSAccessKeyId=xxx&Expires=1712955738&Signature=xxx",
  "status": "https://api.kevel.co/v1/itemdb/ingest-status?folder=products&file=2024-04-12T20%3A02%3A18.425674978-products.ndjson"
}
```