---
title: "Start a full catalog export (async job)"
method: POST
path: "/api/v1/exports"
tags: ["Bulk"]
---

# Start a full catalog export (async job)

`POST /api/v1/exports`

## Request

- Base URL: `https://www.adadiamonds.com`
- URL: `https://www.adadiamonds.com/api/v1/exports`
- Auth: one of:
  - none
  - API key in header `X-Ada-Api-Key`
  - OAuth 2 (authorization code, authorization URL `https://www.adadiamonds.com/oauth/authorize`, token URL `https://www.adadiamonds.com/api/oauth/token`; client credentials, token URL `https://www.adadiamonds.com/api/oauth/token`, scopes: `catalog:read`)

Starts an export of the diamonds, engagement ring, or jewelry catalog with the same filters the list endpoint accepts, and answers **202 Accepted** with a `Location` header pointing at the job's status URL. Exports complete within seconds: poll `status_url` (honouring `Retry-After`) until `status` is `succeeded`, then download `result_url`. Job ids are self-contained signed tokens valid for 24 hours; there is nothing to cancel.

## Request body

- ExportRequest
  - `type` 'diamonds' | 'engagement-rings' | 'jewelry', required
  - `format` 'jsonl' | 'json': `jsonl` streams one product per line; `json` returns one array.
  - `filters` object: Same query keys as the matching list endpoint (e.g. `shape`, `min_price`). Unknown keys are ignored.

## Response `202`

The export job was accepted. Poll the `Location` URL.

- Job
  - `object` 'job', required
  - `id` string, required: Opaque signed job id. Valid for 24 hours.
  - `type` 'export', required
  - `status` 'queued' | 'succeeded', required
  - `progress` integer
  - `export` object
    - `type` 'diamonds' | 'engagement-rings' | 'jewelry'
    - `format` 'jsonl' | 'json'
    - `filters` object
  - `status_url` string, uri, required
  - `result_url` string, uri, nullable: Set once `status` is `succeeded`.
  - `created_at` string, date-time, required
  - `completed_at` string, date-time, nullable
  - `expires_at` string, date-time, required
  - `note` string

## Other responses

- `400`: The request was malformed. `error_description` says which field.
- `429`: Over the rate limit. Wait `Retry-After` seconds; a credential raises the limit.
- `503`: The feature is not configured in this environment. Retry after `Retry-After`.

---

[API](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api.md) · [All operations](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/revisions/2b2ed3201815?raw)