makeup.land V1 API

# makeup.land API — OpenAPI 3.1.0
# Harvested VERBATIM from https://makeup.land/openapi.json on 2026-09-19 (HTTP 200, application/json, 149,073 bytes)
# and re-serialized to YAML without any content change. The byte-for-byte original is openapi/_original/makeup-land-openapi.json.
# Ownership: servers[] https://makeup.land, info.title 'makeup.land API', info.contact makeup.land — the provider's own host.
# servers[]: https://makeup.land is the provider's declared server and is CORRECT — every path carries the /api/v1 prefix,
# so the effective base is https://makeup.land/api/v1 (as apis.yml, the agent card and RFC 9728 metadata state). Not rewritten.
openapi: 3.1.0
info:
  title: makeup.land API
  version: 1.0.0
  summary: REST API for makeup.land — Hebrew-RTL professional cosmetics storefront with bilingual product data, ILS + ℳ-credit dual-tender pricing, and agent-friendly endpoints.
  description: |-
    All endpoints live under `/api/v1/`. Bearer tokens are issued from the admin panel and carry a scope (`full` / `register` / `giftcards` / `proposals`) plus an optional `read_only` flag. Phone-keyed endpoints (cart, gift cards list, payment links, best deals) accept a phone in the query string instead. The public `/gift-cards/validate` endpoint is the only fully unauthenticated route.

    Catalog is Hebrew-primary (he-IL); monetary values that end in `_cents` are integer agorot (100 = ₪1). Products can also be priceable in ℳ-credits — see `credit_price` on variants.

    ## Versioning & deprecation policy

    The current major version is `v1`, exposed under `/api/v1/`. Breaking changes always land under a new major version path (`/api/v2/`); additive changes (new optional fields, new endpoints, new error_code values) ship in-place on `v1` without notice.

    When an endpoint or field is scheduled for removal, responses include the `Deprecation: true` and `Sunset: <RFC 7231 HTTP-date>` headers (per RFC 8594 / RFC 9745) for at least 6 months before the sunset date, with a `Link: <docs>; rel="deprecation"` header pointing at the migration guide. No V1 endpoint is currently deprecated.

    ## Error handling

    Every error response carries `{ error: <human-readable>, error_code: <enum> }` plus situational extras (e.g. `available`, `requested` on `409 insufficient_stock`; `row_errors` on `422 validation_failed`). `error_code` is the stable contract — agents should branch on it. The `error` string may shift in copy or language.

    ## Idempotency

    Mutation endpoints (POST/PATCH/DELETE) accept an `Idempotency-Key` request header. Retries with the same key inside a 24h window are guaranteed to be either no-ops or replays of the original response, never duplicate effects. Recommended pattern: a UUIDv4 generated by the caller per logical operation.
  contact:
    name: makeup.land
    url: https://makeup.land
  license:
    name: Proprietary
    url: https://makeup.land/terms-of-service
servers:
- url: https://makeup.land
  description: Production
tags:
- name: Products
  description: Catalog browsing + semantic search
- name: Brands
  description: Brand directory
- name: Customers
  description: Customer CRUD + tags + opportunities + best deals
- name: Cart
  description: Phone-keyed cart read/write (ILS + ℳ-credits)
- name: Orders
  description: Customer order history
- name: Gift Cards
  description: Recipient cards, validation, redemption
- name: Payment Links
  description: Outstanding payment requests
- name: Register
  description: External registration intake + audit


# --- truncated at 32 KB (237 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/makeup-land/refs/heads/main/openapi/makeup-land-openapi.yml