--- title: "Run several read requests in one call" method: POST path: "/api/v1/batch" tags: ["Bulk"] --- # Run several read requests in one call `POST /api/v1/batch` ## Request - Base URL: `https://www.adadiamonds.com` - URL: `https://www.adadiamonds.com/api/v1/batch` - 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`) Executes up to 20 GET requests against the public read endpoints in a single round trip and returns each sub-response with its own status and body. The batch always answers 200 once the envelope is valid, even if individual items fail, so check each item's `status`. Only the read endpoints listed in the `allowed_paths` of an error item can be batched; a batch counts as one request against the rate limit. ## Request body - BatchRequest - `requests` BatchRequestItem[], required - `id` string: Echoed back on the matching response. Defaults to the item's index. - `method` 'GET' - `path` string, required: Absolute API path of a public read endpoint. - `query` object: Query parameters, exactly as the endpoint documents them. ## Response `200` Every sub-response, in request order. - BatchResponse - `object` 'batch', required - `count` integer, required - `responses` BatchResponseItem[], required - `id` string, required - `status` integer, required: The HTTP status the endpoint would have returned. - `body` union, required: The endpoint's JSON body, or an Error object for a rejected item. - DiamondList - `object` 'list', required - `currency` 'USD', required - `data` Diamond[], required - `object` 'diamond': Present on single-item responses. - `currency` 'USD' - `id` string, required - `name` string, required - `url` string, uri, required - `price` number, nullable, required: USD, loose stone only. - `carat` number, nullable - `shape` string, nullable - `color` string, nullable - `clarity` string, nullable - `cut` string, nullable - `certificate` string, nullable: Grading report number. - `lab` string, nullable: Grading laboratory (GCAL, IGI, GIA). - `measurements` string, nullable - `lengthToWidthRatio` number, nullable - `pagination` Pagination, required - `total` integer, required: Matches before pagination. - `limit` integer, required - `offset` integer, required - `has_more` boolean, required: Whether `offset + limit` would return more. - Diamond - `object` 'diamond': Present on single-item responses. - `currency` 'USD' - `id` string, required - `name` string, required - `url` string, uri, required - `price` number, nullable, required: USD, loose stone only. - `carat` number, nullable - `shape` string, nullable - `color` string, nullable - `clarity` string, nullable - `cut` string, nullable - `certificate` string, nullable: Grading report number. - `lab` string, nullable: Grading laboratory (GCAL, IGI, GIA). - `measurements` string, nullable - `lengthToWidthRatio` number, nullable - EngagementRingList - `object` 'list', required - `currency` 'USD', required - `price_note` string - `data` EngagementRing[], required - `object` 'engagement_ring' - `currency` 'USD' - `price_note` string - `sku` string, required - `title` string, required - `url` string, uri, required - `shapes` string[], required - `style` string, nullable - `type` string, nullable - `priceFrom` number, nullable, required: USD. Setting only; excludes the center diamond. - `platinumUpcharge` number, nullable: USD added for platinum. - `twoToneUpcharge` number, nullable: USD added for a two-tone setting. - `images` ProductImage[], required - `metal` string, required - `view` 'primary' | 'alternate', required - `url` string, uri, required - `alt` string, nullable - `pagination` Pagination, required - `total` integer, required: Matches before pagination. - `limit` integer, required - `offset` integer, required - `has_more` boolean, required: Whether `offset + limit` would return more. - EngagementRing - `object` 'engagement_ring' - `currency` 'USD' - `price_note` string - `sku` string, required - `title` string, required - `url` string, uri, required - `shapes` string[], required - `style` string, nullable - `type` string, nullable - `priceFrom` number, nullable, required: USD. Setting only; excludes the center diamond. - `platinumUpcharge` number, nullable: USD added for platinum. - `twoToneUpcharge` number, nullable: USD added for a two-tone setting. - `images` ProductImage[], required - `metal` string, required - `view` 'primary' | 'alternate', required - `url` string, uri, required - `alt` string, nullable - JewelryList - `object` 'list', required - `currency` 'USD', required - `data` JewelryItem[], required - `object` 'jewelry_item' - `currency` 'USD' - `sku` string, required - `title` string, required - `url` string, uri, required - `category` string, nullable - `type` string, nullable - `subtype` string, nullable - `shapes` string[], required - `priceFrom` number, nullable, required: USD. - `priceMax` number, nullable: USD. - `images` ProductImage[], required - `metal` string, required - `view` 'primary' | 'alternate', required - `url` string, uri, required - `alt` string, nullable - `pagination` Pagination, required - `total` integer, required: Matches before pagination. - `limit` integer, required - `offset` integer, required - `has_more` boolean, required: Whether `offset + limit` would return more. - JewelryItem - `object` 'jewelry_item' - `currency` 'USD' - `sku` string, required - `title` string, required - `url` string, uri, required - `category` string, nullable - `type` string, nullable - `subtype` string, nullable - `shapes` string[], required - `priceFrom` number, nullable, required: USD. - `priceMax` number, nullable: USD. - `images` ProductImage[], required - `metal` string, required - `view` 'primary' | 'alternate', required - `url` string, uri, required - `alt` string, nullable - ArticleList - `object` 'list', required - `data` ArticleSummary[], required - `slug` string, required - `title` string, required - `excerpt` string, nullable - `url` string, uri, required - `markdown_url` string, uri, required - `updated_at` string, date-time - `pagination` Pagination, required - `total` integer, required: Matches before pagination. - `limit` integer, required - `offset` integer, required - `has_more` boolean, required: Whether `offset + limit` would return more. - Article - `object` 'article', required - `slug` string, required - `title` string, required - `excerpt` string, nullable - `author` string, nullable - `published_at` string, nullable - `url` string, uri, required - `markdown_url` string, uri - `body_markdown` string, required - ShowroomList - `object` 'list', required - `data` Showroom[], required - `name` string, required - `url` string, uri, required - `streetAddress` string, required - `addressLocality` string, required - `addressRegion` string, required - `postalCode` string, required - `addressCountry` string, required - `telephone` string, required - `hours` string, required - `appointmentRequired` boolean, required - `virtual_consultations` VirtualConsultations, required - `available` boolean - `description` string - `book_url` string, uri - `email` string, email - `telephone` string - Error - `error` string, required: Stable machine-readable code. - `error_description` string, required: What went wrong and what to do about it. - `documentation_url` string, uri ## 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. --- [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)