# Bidali gift card store API

> A free, read-only JSON API for the gift card catalogue on this site: countries, categories, currencies and brands, with amounts, redemption instructions and terms. No sign-up and no API key.

## Your first requests

Every endpoint is a GET request that returns JSON. Copy a command and run it.

List the countries with gift cards

```sh
curl -s https://giftcards.bidali.com/api/v1/countries
```

Find grocery gift cards in Canada

```sh
curl -s "https://giftcards.bidali.com/api/v1/countries/canada/brands?category=groceries&limit=5"
```

Get one brand: amounts, redemption and terms

```sh
curl -s https://giftcards.bidali.com/api/v1/countries/canada/brands/doordash-ca
```

Read any page as Markdown

```sh
curl -s -H "Accept: text/markdown" https://giftcards.bidali.com/brands/canada/doordash-ca
```

## Endpoints

- `GET /api/v1`: Describe the Catalogue API
- `GET /api/v1/countries`: List the countries with gift cards
- `GET /api/v1/categories`: List the gift card categories
- `GET /api/v1/currencies`: List the currencies gift cards are priced in
- `GET /api/v1/countries/{country}/brands`: List the brands on sale in a country
- `GET /api/v1/countries/{country}/brands/{brand}`: Get one brand: amounts, redemption and terms
- `GET /api/v1/openapi.json`: Get this OpenAPI document as JSON
- `GET /api/v1/openapi.yaml`: Get this OpenAPI document as YAML

## Everything an agent can read

- OpenAPI 3.1: https://giftcards.bidali.com/openapi.json · https://giftcards.bidali.com/openapi.yaml
- Markdown: `Accept: text/markdown`, or https://giftcards.bidali.com/index.md
- llms.txt: https://giftcards.bidali.com/llms.txt
- Sitemap: https://giftcards.bidali.com/sitemap.xml

## Errors

Errors are JSON, with the HTTP status that fits: 400 for a missing or invalid parameter, 404 for an unknown country, brand or path, 405 for any method but GET, and 502 or 504 when the catalogue service fails. The code field does not change; the hint field says what to do next.

```json
{ "error": { "code": "country_not_found", "message": "No country matches \"atlantis\".", "hint": "Use a slug or an ISO 3166-1 alpha-2 code from GET /api/v1/countries.", "docs": "https://giftcards.bidali.com/developers#errors" } }
```

Responses are cached for up to five minutes. A page holds at most 100 brands: follow pagination.next for the rest.

## Buy gift cards with the Bidali Gift Card API

This API only reads the catalogue. To buy gift cards from your own software or an AI agent, use the Bidali Gift Card API. It works with API keys and is in early access.

- Read the docs: https://docs.bidali.com
- Gift Card API: https://www.bidali.com/products/gift-card-api
- Talk to sales: https://www.bidali.com/contact?intent=sales

MCP access is coming.

## Other formats

- HTML page: https://giftcards.bidali.com/developers
- This page as Markdown: https://giftcards.bidali.com/developers.md
- Same data as JSON (Catalogue API): https://giftcards.bidali.com/api/v1
- Guide to this store for AI agents: https://giftcards.bidali.com/llms.txt
- Catalogue API reference (OpenAPI 3.1): https://giftcards.bidali.com/openapi.json

## Languages

[English](https://giftcards.bidali.com/developers.md) · [Español](https://giftcards.bidali.com/es/developers.md) · [Português](https://giftcards.bidali.com/pt/developers.md) · [Français](https://giftcards.bidali.com/fr/developers.md) · [Deutsch](https://giftcards.bidali.com/de/developers.md) · [Italiano](https://giftcards.bidali.com/it/developers.md) · [Polski](https://giftcards.bidali.com/pl/developers.md) · [Svenska](https://giftcards.bidali.com/sv/developers.md)