openapi: 3.2.0 info: title: Monocrawl Sephora API version: 0.1.0 description: One key, one envelope, one credit meter across social, search, commerce and web data. contact: name: Monocrawl support url: https://www.monocrawl.com/contact termsOfService: https://www.monocrawl.com/legal/terms-and-conditions servers: - url: https://www.monocrawl.com security: - ApiKeyHeader: [] tags: - name: Sephora paths: /v1/sephora/availability: get: operationId: sephora_availability tags: - Sephora summary: Sephora store availability description: Which stores near a point stock one sku, with distance and in-store availability. Costs 3 credits per successful live response. parameters: - name: sku_id in: query required: true schema: type: string example: '2495505' description: Sku id from sephora/product - name: latitude in: query required: true schema: type: string example: '41.7887' description: Latitude - name: longitude in: query required: true schema: type: string example: '-87.7665' description: Longitude - name: radius in: query required: false schema: type: string example: '50' description: Miles - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/availability.json title: sephora/availability data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: _warnings: description: Optional warnings supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: address: description: Optional address supplied by this operation. Null means unknown. type: - string - 'null' address_parts: description: Optional address parts supplied by this operation. Null means unknown. type: - object - 'null' properties: city: description: Optional city supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' line1: description: Optional line1 supplied by this operation. Null means unknown. type: - string - 'null' line2: description: Optional line2 supplied by this operation. Null means unknown. type: - string - 'null' mall: description: Optional mall supplied by this operation. Null means unknown. type: - string - 'null' postal_code: description: Optional postal code supplied by this operation. Null means unknown. type: - string - 'null' state: description: Optional state supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true availability: description: Optional availability supplied by this operation. Null means unknown. type: - object - 'null' properties: in_store: description: Optional in store supplied by this operation. Null means unknown. type: - number - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true curbside: description: Optional curbside supplied by this operation. Null means unknown. type: - boolean - 'null' distance_miles: description: Optional distance miles supplied by this operation. Null means unknown. type: - number - 'null' hours: description: Optional hours supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' latitude: description: Optional latitude supplied by this operation. Null means unknown. type: - number - 'null' longitude: description: Optional longitude supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' phone: description: Optional phone supplied by this operation. Null means unknown. type: - string - 'null' pickup: description: Optional pickup supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' timezone: description: Optional timezone supplied by this operation. Null means unknown. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - address properties: address: description: Optional address supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - address_parts properties: address_parts: description: Optional address parts supplied by this operation. Null means unknown. type: - object properties: city: description: Optional city supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' line1: description: Optional line1 supplied by this operation. Null means unknown. type: - string - 'null' line2: description: Optional line2 supplied by this operation. Null means unknown. type: - string - 'null' mall: description: Optional mall supplied by this operation. Null means unknown. type: - string - 'null' postal_code: description: Optional postal code supplied by this operation. Null means unknown. type: - string - 'null' state: description: Optional state supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - availability properties: availability: description: Optional availability supplied by this operation. Null means unknown. type: - object properties: in_store: description: Optional in store supplied by this operation. Null means unknown. type: - number - 'null' status: description: Optional status supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - curbside properties: curbside: description: Optional curbside supplied by this operation. Null means unknown. type: - boolean - required: - distance_miles properties: distance_miles: description: Optional distance miles supplied by this operation. Null means unknown. type: - number - required: - hours properties: hours: description: Optional hours supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - latitude properties: latitude: description: Optional latitude supplied by this operation. Null means unknown. type: - number - required: - longitude properties: longitude: description: Optional longitude supplied by this operation. Null means unknown. type: - number - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - phone properties: phone: description: Optional phone supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - pickup properties: pickup: description: Optional pickup supplied by this operation. Null means unknown. type: - boolean - required: - timezone properties: timezone: description: Optional timezone supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 messages: description: Optional messages supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - _warnings: - example count: 0 has_more: false items: - address: example address_parts: city: example country: example line1: example line2: example mall: example postal_code: example state: example availability: in_store: 0 status: example curbside: false distance_miles: 0 hours: - {} id: example kind: example latitude: 0 longitude: 0 name: example phone: example pickup: false platform: example timezone: example type: example url: https://example.com/example messages: - example sku_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/brand-products: get: operationId: sephora_brand_products tags: - Sephora summary: Sephora brand products description: Products of one brand, sixty per page. Costs 3 credits per successful live response. parameters: - name: brand in: query required: true schema: type: string example: gucci description: Brand name from sephora/brands - name: page in: query required: false schema: type: string example: '1' description: Page number (60 per page) - name: sort in: query required: false schema: type: string enum: - best_selling - bestselling - top_rated - rating - price_low_to_high - price_asc - price_high_to_low - price_desc - new - newest example: best_selling description: 'best_selling, top_rated, price_low_to_high, price_high_to_low or new Accepted values: best_selling, bestselling, top_rated, rating, price_low_to_high, price_asc, price_high_to_low, price_desc, new, newest. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/brand-products.json title: sephora/brand-products data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - 'null' brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' currency: description: Optional currency supplied by this operation. Null means unknown. type: - string - 'null' exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - 'null' new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - object - 'null' properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - bestseller properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - required: - brand properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - currency properties: currency: description: Optional currency supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - exclusive properties: exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - limited_edition properties: limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - required: - new properties: new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - required: - price properties: price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - required: - rating properties: rating: description: Source rating; read its accompanying scale and vote count. type: - object properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - sku_id properties: sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 page: description: Optional page supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - brand: example count: 0 cursor: null has_more: false items: - bestseller: false brand: example currency: example exclusive: false id: example image: https://example.com/example limited_edition: false new: false platform: example price: 0 rating: max: 0 value: 0 sku_id: example title: example type: example url: https://example.com/example page: 0 total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/brands: get: operationId: sephora_brands tags: - Sephora summary: Sephora brands description: Every brand the storefront lists, with ids and URLs. Costs 1 credit per successful live response. parameters: - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/brands.json title: sephora/brands data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - id: example name: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/categories: get: operationId: sephora_categories tags: - Sephora summary: Sephora categories description: The storefront's top-level categories with ids for sephora/category. Costs 1 credit per successful live response. parameters: - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/categories.json title: sephora/categories data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: children: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} has_children: description: Optional has children supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - children properties: children: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - has_children properties: has_children: description: Optional has children supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - children: [] has_children: false id: example image: https://example.com/example name: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/category: get: operationId: sephora_category tags: - Sephora summary: Sephora category products description: Products in a category, sixty per page. Costs 3 credits per successful live response. parameters: - name: id in: query required: true schema: type: string example: cat130054 description: Category id from sephora/categories - name: page in: query required: false schema: type: string example: '1' description: Page number (60 per page) - name: sort in: query required: false schema: type: string enum: - best_selling - bestselling - top_rated - rating - price_low_to_high - price_asc - price_high_to_low - price_desc - new - newest example: best_selling description: 'best_selling, top_rated, price_low_to_high, price_high_to_low or new Accepted values: best_selling, bestselling, top_rated, rating, price_low_to_high, price_asc, price_high_to_low, price_desc, new, newest. Case, spaces, hyphens and underscores are interchangeable.' - name: min_price in: query required: false schema: type: string example: '' description: Minimum price - name: max_price in: query required: false schema: type: string example: '' description: Maximum price - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/category.json title: sephora/category data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: category_id: description: Optional category id supplied by this operation. Null means unknown. type: - string - 'null' count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - 'null' brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' currency: description: Optional currency supplied by this operation. Null means unknown. type: - string - 'null' exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - 'null' new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - object - 'null' properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - bestseller properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - required: - brand properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - currency properties: currency: description: Optional currency supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - exclusive properties: exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - limited_edition properties: limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - required: - new properties: new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - required: - price properties: price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - required: - rating properties: rating: description: Source rating; read its accompanying scale and vote count. type: - object properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - reviews_count properties: reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - required: - sku_id properties: sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 page: description: Optional page supplied by this operation. Null means unknown. type: - number - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - category_id: example count: 0 cursor: null has_more: false items: - bestseller: false brand: example currency: example exclusive: false id: example image: https://example.com/example limited_edition: false new: false platform: example price: 0 rating: max: 0 value: 0 votes: 0 reviews_count: 0 sku_id: example title: example type: example url: https://example.com/example page: 0 total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/category-tree: get: operationId: sephora_category_tree tags: - Sephora summary: Sephora category children description: The child categories of one category. Costs 1 credit per successful live response. parameters: - name: id in: query required: true schema: type: string example: cat160006 description: Category id - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/category-tree.json title: sephora/category-tree data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: children: description: Optional children supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: children: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} has_children: description: Optional has children supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - children properties: children: description: Optional children supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: children: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} has_children: description: Optional has children supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - children: - children: [] has_children: false id: example name: example url: https://example.com/example id: example platform: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/product: get: operationId: sephora_product tags: - Sephora summary: Sephora product description: 'One product: brand, price, rating and review count, loves, description, usage, images and its shade or size variants. Costs 3 credits per successful live response.' parameters: - name: id in: query required: true schema: type: string example: P427414 description: Product id (P-number), or the product URL - name: sku_id in: query required: false schema: type: string example: '2025633' description: A shade or size sku id - name: language in: query required: false schema: type: string enum: - en-US - en-CA - fr-CA example: en-US description: 'en-US, en-CA or fr-CA Accepted values: en-US, en-CA, fr-CA. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/product.json title: sephora/product data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' brand_id: description: Optional brand id supplied by this operation. Null means unknown. type: - string - 'null' brand_url: description: Optional brand url supplied by this operation. Null means unknown. type: - string - 'null' currency: description: Optional currency supplied by this operation. Null means unknown. type: - string - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' images: description: Optional images supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' loves: description: Optional loves supplied by this operation. Null means unknown. type: - number - 'null' out_of_stock: description: Optional out of stock supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - object - 'null' properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - 'null' short_description: description: Optional short description supplied by this operation. Null means unknown. type: - string - 'null' size: description: Optional size supplied by this operation. Null means unknown. type: - string - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' usage: description: Optional usage supplied by this operation. Null means unknown. type: - string - 'null' variants: description: Optional variants supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' out_of_stock: description: Optional out of stock supplied by this operation. Null means unknown. type: - boolean - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' variation: description: Optional variation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true variation: description: Optional variation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - brand properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - brand_id properties: brand_id: description: Optional brand id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - brand_url properties: brand_url: description: Optional brand url supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - currency properties: currency: description: Optional currency supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - images properties: images: description: Optional images supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - loves properties: loves: description: Optional loves supplied by this operation. Null means unknown. type: - number - required: - out_of_stock properties: out_of_stock: description: Optional out of stock supplied by this operation. Null means unknown. type: - boolean - required: - price properties: price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - required: - rating properties: rating: description: Source rating; read its accompanying scale and vote count. type: - object properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - reviews_count properties: reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - required: - short_description properties: short_description: description: Optional short description supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - size properties: size: description: Optional size supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - sku_id properties: sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - usage properties: usage: description: Optional usage supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - variants properties: variants: description: Optional variants supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' out_of_stock: description: Optional out of stock supplied by this operation. Null means unknown. type: - boolean - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' variation: description: Optional variation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - variation properties: variation: description: Optional variation supplied by this operation. Null means unknown. type: - string minLength: 1 x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - brand: example brand_id: example brand_url: https://example.com/example currency: example description: example id: example image: https://example.com/example images: - example loves: 0 out_of_stock: false platform: example price: 0 rating: max: 0 value: 0 votes: 0 reviews_count: 0 short_description: example size: example sku_id: example title: example type: example url: https://example.com/example usage: example variants: - image: https://example.com/example out_of_stock: false price: 0 sku_id: example url: https://example.com/example variation: example variation: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/reviews: get: operationId: sephora_reviews tags: - Sephora summary: Sephora product reviews description: Reviews of a product with author, rating, recommendation, verified-purchase badge, photos and helpfulness votes. Costs 3 credits per successful live response. parameters: - name: id in: query required: true schema: type: string example: P458747 description: Product id (P-number) - name: limit in: query required: false schema: type: string example: '6' description: Reviews per page, up to 30 - name: offset in: query required: false schema: type: string example: '0' description: Offset for the next page - name: sort in: query required: false schema: type: string enum: - most_helpful - highest_rating - lowest_rating - oldest - newest example: most_helpful description: 'most_helpful, highest_rating, lowest_rating, oldest or newest Accepted values: most_helpful, highest_rating, lowest_rating, oldest, newest. Case, spaces, hyphens and underscores are interchangeable.' - name: rating in: query required: false schema: type: string example: '' description: Only this star rating, 1-5 - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/reviews.json title: sephora/reviews data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: author: description: Public author information supplied with this record. type: - string - 'null' featured: description: Optional featured supplied by this operation. Null means unknown. type: - boolean - 'null' helpful: description: Optional helpful supplied by this operation. Null means unknown. type: - number - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' photos: description: Optional photos supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' posted_at: description: Optional posted at supplied by this operation. Null means unknown. type: - string - 'null' product_id: description: Optional product id supplied by this operation. Null means unknown. type: - string - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - number - 'null' recommended: description: Optional recommended supplied by this operation. Null means unknown. type: - boolean - 'null' responses: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} syndicated: description: Optional syndicated supplied by this operation. Null means unknown. type: - boolean - 'null' tags: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array - 'null' items: {} text: description: Source text when supplied. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' unhelpful: description: Optional unhelpful supplied by this operation. Null means unknown. type: - number - 'null' verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean - 'null' additionalProperties: true allOf: - anyOf: - required: - author properties: author: description: Public author information supplied with this record. type: - string minLength: 1 - required: - featured properties: featured: description: Optional featured supplied by this operation. Null means unknown. type: - boolean - required: - helpful properties: helpful: description: Optional helpful supplied by this operation. Null means unknown. type: - number - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - photos properties: photos: description: Optional photos supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - string - 'null' - required: - posted_at properties: posted_at: description: Optional posted at supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - product_id properties: product_id: description: Optional product id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - rating properties: rating: description: Source rating; read its accompanying scale and vote count. type: - number - required: - recommended properties: recommended: description: Optional recommended supplied by this operation. Null means unknown. type: - boolean - required: - responses properties: responses: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - syndicated properties: syndicated: description: Optional syndicated supplied by this operation. Null means unknown. type: - boolean - required: - tags properties: tags: description: Source array was empty in the reviewed captures; item fields remain unspecified. type: - array items: {} - required: - text properties: text: description: Source text when supplied. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - unhelpful properties: unhelpful: description: Optional unhelpful supplied by this operation. Null means unknown. type: - number - required: - verified properties: verified: description: Optional verified supplied by this operation. Null means unknown. type: - boolean limit: description: Optional limit supplied by this operation. Null means unknown. type: - number - 'null' offset: description: Optional offset supplied by this operation. Null means unknown. type: - number - 'null' product_id: description: Optional product id supplied by this operation. Null means unknown. type: - string - 'null' total: description: Source-reported total; null is unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null has_more: false items: - author: example featured: false helpful: 0 id: example photos: - example platform: example posted_at: '2026-09-01T12:00:00Z' product_id: example rating: 0 recommended: false responses: [] syndicated: false tags: [] text: example title: example unhelpful: 0 verified: false limit: 0 offset: 0 product_id: example total: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/search: get: operationId: sephora_search tags: - Sephora summary: Sephora product search description: Products matching a keyword, sixty per page, with brand, price, rating and badges. Costs 3 credits per successful live response. parameters: - name: query in: query required: true schema: type: string example: eyeshadow description: Search keyword - name: page in: query required: false schema: type: string example: '1' description: Page number (60 per page) - name: sort in: query required: false schema: type: string enum: - best_selling - bestselling - top_rated - rating - price_low_to_high - price_asc - price_high_to_low - price_desc - new - newest example: best_selling description: 'best_selling, top_rated, price_low_to_high, price_high_to_low or new Accepted values: best_selling, bestselling, top_rated, rating, price_low_to_high, price_asc, price_high_to_low, price_desc, new, newest. Case, spaces, hyphens and underscores are interchangeable.' - name: category_id in: query required: false schema: type: string example: '' description: Category id from sephora/categories - name: min_price in: query required: false schema: type: string example: '' description: Minimum price - name: max_price in: query required: false schema: type: string example: '' description: Maximum price - name: min_rating in: query required: false schema: type: string example: '' description: Minimum rating, 1-5 - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/search.json title: sephora/search data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' cursor: description: Opaque next-page token; pass it back unchanged. Null does not prove complete history. type: - string - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - 'null' brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' currency: description: Optional currency supplied by this operation. Null means unknown. type: - string - 'null' exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - 'null' new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - object - 'null' properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - 'null' sale_price: description: Optional sale price supplied by this operation. Null means unknown. type: - number - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - bestseller properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - required: - brand properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - currency properties: currency: description: Optional currency supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - exclusive properties: exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - limited_edition properties: limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - required: - new properties: new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - required: - price properties: price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - required: - rating properties: rating: description: Source rating; read its accompanying scale and vote count. type: - object properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - reviews_count properties: reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - required: - sale_price properties: sale_price: description: Optional sale price supplied by this operation. Null means unknown. type: - number - required: - sku_id properties: sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 page: description: Optional page supplied by this operation. Null means unknown. type: - number - 'null' query: description: Optional query supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 cursor: null has_more: false items: - bestseller: false brand: example currency: example exclusive: false id: example image: https://example.com/example limited_edition: false new: false platform: example price: 0 rating: max: 0 value: 0 votes: 0 reviews_count: 0 sale_price: 0 sku_id: example title: example type: example url: https://example.com/example page: 0 query: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/similar: get: operationId: sephora_similar tags: - Sephora summary: Sephora similar products description: Products the storefront recommends alongside one product. Costs 3 credits per successful live response. parameters: - name: id in: query required: true schema: type: string example: P510799 description: Product id (P-number) - name: limit in: query required: false schema: type: string example: '' description: How many - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/similar.json title: sephora/similar data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - 'null' brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' currency: description: Optional currency supplied by this operation. Null means unknown. type: - string - 'null' description: description: Source description; null or absent means not supplied. type: - string - 'null' exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - 'null' id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - 'null' new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - 'null' on_sale: description: Optional on sale supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - 'null' rating: description: Source rating; read its accompanying scale and vote count. type: - object - 'null' properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - 'null' sale_price: description: Optional sale price supplied by this operation. Null means unknown. type: - number - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' title: description: Source title when supplied. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' variation: description: Optional variation supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - bestseller properties: bestseller: description: Optional bestseller supplied by this operation. Null means unknown. type: - boolean - required: - brand properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - currency properties: currency: description: Optional currency supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - description properties: description: description: Source description; null or absent means not supplied. type: - string minLength: 1 - required: - exclusive properties: exclusive: description: Optional exclusive supplied by this operation. Null means unknown. type: - boolean - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - limited_edition properties: limited_edition: description: Optional limited edition supplied by this operation. Null means unknown. type: - boolean - required: - new properties: new: description: Optional new supplied by this operation. Null means unknown. type: - boolean - required: - on_sale properties: on_sale: description: Optional on sale supplied by this operation. Null means unknown. type: - boolean - required: - price properties: price: description: Source price. Currency, taxes and availability depend on the listing. type: - number - required: - rating properties: rating: description: Source rating; read its accompanying scale and vote count. type: - object properties: max: description: Optional max supplied by this operation. Null means unknown. type: - number - 'null' value: description: Optional value supplied by this operation. Null means unknown. type: - number - 'null' votes: description: Optional votes supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true - required: - reviews_count properties: reviews_count: description: Optional reviews count supplied by this operation. Null means unknown. type: - number - required: - sale_price properties: sale_price: description: Optional sale price supplied by this operation. Null means unknown. type: - number - required: - sku_id properties: sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - title properties: title: description: Source title when supplied. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 - required: - variation properties: variation: description: Optional variation supplied by this operation. Null means unknown. type: - string minLength: 1 product_id: description: Optional product id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - bestseller: false brand: example currency: example description: example exclusive: false id: example image: https://example.com/example limited_edition: false new: false on_sale: false platform: example price: 0 rating: max: 0 value: 0 votes: 0 reviews_count: 0 sale_price: 0 sku_id: example title: example type: example url: https://example.com/example variation: example product_id: example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 3 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/stores: get: operationId: sephora_stores tags: - Sephora summary: Sephora stores near a point description: Stores near a point with address, phone, hours, pickup and curbside flags. Costs 1 credit per successful live response. parameters: - name: latitude in: query required: true schema: type: string example: '37.4419' description: Latitude - name: longitude in: query required: true schema: type: string example: '-122.1430' description: Longitude - name: radius in: query required: false schema: type: string example: '50' description: Miles - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/stores.json title: sephora/stores data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: address: description: Optional address supplied by this operation. Null means unknown. type: - string - 'null' address_parts: description: Optional address parts supplied by this operation. Null means unknown. type: - object - 'null' properties: city: description: Optional city supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' line1: description: Optional line1 supplied by this operation. Null means unknown. type: - string - 'null' line2: description: Optional line2 supplied by this operation. Null means unknown. type: - string - 'null' mall: description: Optional mall supplied by this operation. Null means unknown. type: - string - 'null' postal_code: description: Optional postal code supplied by this operation. Null means unknown. type: - string - 'null' state: description: Optional state supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true curbside: description: Optional curbside supplied by this operation. Null means unknown. type: - boolean - 'null' distance_miles: description: Optional distance miles supplied by this operation. Null means unknown. type: - number - 'null' hours: description: Optional hours supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true id: description: Source identifier. Preserve the supplied type and exact value. type: - string - 'null' kind: description: Optional kind supplied by this operation. Null means unknown. type: - string - 'null' latitude: description: Optional latitude supplied by this operation. Null means unknown. type: - number - 'null' longitude: description: Optional longitude supplied by this operation. Null means unknown. type: - number - 'null' name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' phone: description: Optional phone supplied by this operation. Null means unknown. type: - string - 'null' pickup: description: Optional pickup supplied by this operation. Null means unknown. type: - boolean - 'null' platform: description: Optional platform supplied by this operation. Null means unknown. type: - string - 'null' timezone: description: Optional timezone supplied by this operation. Null means unknown. type: - string - 'null' type: description: Optional type supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - address properties: address: description: Optional address supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - address_parts properties: address_parts: description: Optional address parts supplied by this operation. Null means unknown. type: - object properties: city: description: Optional city supplied by this operation. Null means unknown. type: - string - 'null' country: description: Optional country supplied by this operation. Null means unknown. type: - string - 'null' line1: description: Optional line1 supplied by this operation. Null means unknown. type: - string - 'null' line2: description: Optional line2 supplied by this operation. Null means unknown. type: - string - 'null' mall: description: Optional mall supplied by this operation. Null means unknown. type: - string - 'null' postal_code: description: Optional postal code supplied by this operation. Null means unknown. type: - string - 'null' state: description: Optional state supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true - required: - curbside properties: curbside: description: Optional curbside supplied by this operation. Null means unknown. type: - boolean - required: - distance_miles properties: distance_miles: description: Optional distance miles supplied by this operation. Null means unknown. type: - number - required: - hours properties: hours: description: Optional hours supplied by this operation. Null means unknown. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: {} additionalProperties: true - required: - id properties: id: description: Source identifier. Preserve the supplied type and exact value. type: - string minLength: 1 - required: - latitude properties: latitude: description: Optional latitude supplied by this operation. Null means unknown. type: - number - required: - longitude properties: longitude: description: Optional longitude supplied by this operation. Null means unknown. type: - number - required: - name properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - phone properties: phone: description: Optional phone supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - pickup properties: pickup: description: Optional pickup supplied by this operation. Null means unknown. type: - boolean - required: - timezone properties: timezone: description: Optional timezone supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - url properties: url: description: Original source URL when supplied. type: - string minLength: 1 radius_miles: description: Optional radius miles supplied by this operation. Null means unknown. type: - number - 'null' additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - address: example address_parts: city: example country: example line1: example line2: example mall: example postal_code: example state: example curbside: false distance_miles: 0 hours: - {} id: example kind: example latitude: 0 longitude: 0 name: example phone: example pickup: false platform: example timezone: example type: example url: https://example.com/example radius_miles: 0 default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true /v1/sephora/suggestions: get: operationId: sephora_suggestions tags: - Sephora summary: Sephora search suggestions description: Search suggestions for a partial query, with the product each one leads to and the trending categories. Costs 1 credit per successful live response. parameters: - name: query in: query required: true schema: type: string example: eyeshadow description: Partial search text - name: language in: query required: false schema: type: string enum: - en-US - en-CA - fr-CA example: en-US description: 'en-US, en-CA or fr-CA Accepted values: en-US, en-CA, fr-CA. Case, spaces, hyphens and underscores are interchangeable.' - name: dry_run in: query required: false schema: type: string enum: - '1' - '0' - 'true' - 'false' example: '1' description: 'Read a zero-credit estimate without fetching sources, running AI, or reserving credits. Cache status is a snapshot, not a guarantee at execution. Accepted values: 1, 0, true, false. Case, spaces, hyphens and underscores are interchangeable.' - name: X-Max-Credits in: header required: false schema: type: integer minimum: 0 maximum: 9007199254740991 example: 5 description: Optional credit reservation ceiling for this individual request. Send a non-negative integer in decimal digits. Live execution checks the required reservation after resolving free cache hits or buffered continuation, before charging or calling a supplier. A higher reservation returns HTTP 422 INVALID_PARAMETERS with reason max_credits_exceeded and charges nothing. Invalid header values also return 422. Zero permits only a zero-credit reservation; omitting the header uses normal pricing. dry_run remains a free preview. This does not cap later requests, batches or scheduled runs. security: - ApiKeyHeader: [] - BearerKey: [] responses: '200': description: 'The common success envelope; `data` is endpoint-specific. Many lists use items/count/cursor; bundles use named collections and their documented continuation metadata. HTTP 200 can contain a partial bundle: inspect complete, partial and legs where supplied.' content: application/json: schema: allOf: - $ref: '#/components/schemas/Success' - type: object properties: data: $schema: https://json-schema.org/draft/2020-12/schema $id: https://www.monocrawl.com/schemas/sephora/suggestions.json title: sephora/suggestions data fields description: Optional data supplied by this operation. Null means unknown. type: object properties: count: description: Number of records in this response, not lifetime or total matches. type: - number - 'null' has_more: description: Source continuation indicator; null means unknown. type: - boolean - 'null' items: description: Returned records. Source coverage and completeness vary. type: - array items: description: Optional record supplied by this operation. Null means unknown. type: object properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string - 'null' image: description: Optional image supplied by this operation. Null means unknown. type: - string - 'null' product: description: Optional product supplied by this operation. Null means unknown. type: - string - 'null' product_id: description: Optional product id supplied by this operation. Null means unknown. type: - string - 'null' query: description: Optional query supplied by this operation. Null means unknown. type: - string - 'null' sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string - 'null' additionalProperties: true allOf: - anyOf: - required: - brand properties: brand: description: Optional brand supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - image properties: image: description: Optional image supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - product properties: product: description: Optional product supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - product_id properties: product_id: description: Optional product id supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - query properties: query: description: Optional query supplied by this operation. Null means unknown. type: - string minLength: 1 - required: - sku_id properties: sku_id: description: Optional sku id supplied by this operation. Null means unknown. type: - string minLength: 1 query: description: Optional query supplied by this operation. Null means unknown. type: - string - 'null' trending: description: Optional trending supplied by this operation. Null means unknown. type: - array - 'null' items: description: Optional record supplied by this operation. Null means unknown. type: - object - 'null' properties: name: description: Optional name supplied by this operation. Null means unknown. type: - string - 'null' url: description: Original source URL when supplied. type: - string - 'null' additionalProperties: true additionalProperties: true required: - items x-contract-version: '2026-09-22' x-validation-scope: Required success payload structure; optional fields and source completeness remain separate. examples: - count: 0 has_more: false items: - brand: example image: https://example.com/example product: example product_id: example query: example sku_id: example query: example trending: - name: example url: https://example.com/example default: description: The error envelope — the same shape for every non-2xx status. content: application/json: schema: $ref: '#/components/schemas/Error' x-credits: 1 x-production-available: true x-capacity: status: not_assessed message: Capacity is workload-dependent; configured routes do not establish sustained throughput or an availability guarantee. x-availability-scope: Structural check of the effective registered chain, production permission, adapter, configured cost and quality floor without request parameters. True is not a live-health, credential, quota, subscription-entitlement, complete-data or deployment-exposure guarantee. False means no structurally eligible candidate; null means metadata could not establish availability. Composite child capability still depends on its component routes. x-live-proven: true components: schemas: Error: type: object required: - success - error - credits_used - request_id properties: success: const: false error: type: object required: - type - message - status properties: type: type: string enum: - UNAUTHORIZED - KEY_REVOKED - KEY_LIMIT_EXCEEDED - RATE_LIMITED - INSUFFICIENT_CREDITS - RESOURCE_NOT_FOUND - INVALID_PARAMETERS - TARGET_ACCESS_DENIED - UPSTREAM_ERROR - UPSTREAM_TIMEOUT - FREE_CAPACITY_UNAVAILABLE - CAPACITY_UNAVAILABLE - ENDPOINT_NOT_FOUND - ENDPOINT_NOT_AVAILABLE - FAIR_USE_EXCEEDED - INTERNAL_ERROR message: type: string status: type: integer doc_url: type: string description: Deep link to the exact section of the errors guide for this type. details: type: object credits_used: type: - integer - 'null' description: Confirmed net charge; null when billing is pending reconciliation. Inspect error.details.billing_status and retain request_id. credits_remaining: type: integer request_id: type: string Success: type: object required: - success - platform - endpoint - data - credits_used - credits_remaining - request_id properties: _completeness: type: object description: Reported response completeness, not a guarantee of complete platform history. Missing source assertions remain unknown. properties: state: type: string enum: - complete - partial - unknown scope: type: string inspection_limited: type: boolean success: const: true platform: type: string endpoint: type: string description: The resolved path, e.g. `/v1/github/profile`. data: description: Amazon responses include marketplace.country and marketplace.domain (resolved request marketplace, UK by default). X profiles preserve location, bio_link and cover_url when supplied. TikTok profiles preserve commerce_user, seller, region, location and business_category when supplied; region identifies the account region rather than personal residence. TikTok comments use platform_default selection, which can change between fetches; keep the same video and options when following cursors. Amazon review variant is readable text. Facebook profiles preserve cover_url, following and created_at when supplied; likes_count and followers are distinct and follower totals may be rounded. Endpoint-specific normalized payload, not one universal post/profile schema. Many lists use items/count/cursor; a null cursor means no usable next cursor was supplied, not proof that all history was retrieved. Check has_more and warnings where present. Social full-profile bundles use posts_cursor and posts_pagination.next_params; retain all returned next parameters. YouTube channel bundles instead use recent_videos, cursor and recent_videos_pagination. Inspect complete/partial/legs where supplied for bounded or failed components. Optional model-derived fields are labelled, not source facts. credits_used: type: integer credits_remaining: type: integer request_id: type: string cached: type: boolean stale: type: boolean description: True only for an explicitly labelled, zero-credit reference snapshot served after a temporary upstream failure. age_seconds: type: integer minimum: 0 description: Age of a stale snapshot since its original retrieval; not reset by outage recovery. fetched_at: type: string format: date-time description: Original retrieval time of a stale snapshot, in UTC. synthetic: type: boolean description: Present and true only on the explicitly requested /sandbox surface. Synthetic responses are representative and charged 0 credits; production /v1 never returns them. degraded: type: boolean description: Reserved for sandbox compatibility. Production /v1 reports upstream failure as an error and never serves a representative fallback. securitySchemes: ApiKeyHeader: type: apiKey in: header name: x-api-key description: Your API key (`mn_…`), from the console. The recommended style. BearerKey: type: http scheme: bearer description: The same key as a Bearer token, for clients that only expose an Authorization field. Keys are never accepted in the query string — URLs leak into logs and referrers. x-provenance: method: harvested publisher: Monocrawl source: https://www.monocrawl.com/openapi.json note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json); stamped by stamp-openapi-provenance.py (roadmap#793)