> ## Documentation Index > Fetch the complete documentation index at: https://vexioncards.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List icons > Browse the VEXiON cards 3D icon library. 10,000+ icons across 23 categories (Animals, Food & Drink, Technology & Media, etc.) for use as stamp_icon_url on stamp cards or pattern_icon_urls[] on non-stamp cards. **Scope: none required.** The catalog is identical for every organization - curated centrally by VEXiON, containing no organization data - so any authenticated key may read it regardless of its scopes. WHEN to use: - Building a custom icon picker UI in your dashboard - Letting end-customers pick icons for personalization - Discovering icons for specific card designs HOW it works: - Cursor-paginated (default 25, max 100 per page - the same bounds as every other list endpoint) - Ordered by `slug` ascending, NOT newest-first: this is a static catalog with no `created_at` - Filter by category (23 fixed categories returned in response for client-side UI) - Search by free text across icon title + tags (case-insensitive partial match) - Returns image_url directly usable in Card.design.stamp_icon_url or pattern_icon_urls GOTCHAS: - The library is static (curated by VEXiON). Partners cannot add custom icons via this endpoint. - Partners CAN still pass custom URLs to stamp_icon_url / pattern_icon_urls (uploaded to their own CDN). This endpoint just exposes our library. - Heavy caching is fine - the catalog rarely changes (new icons added quarterly). ## OpenAPI ````yaml /openapi.json get /v1/icons openapi: 3.1.0 info: title: VEXiON cards Public API description: >- ## Rate limiting Two independent layers, checked in this order: 1. **Per-IP throttle (pre-authentication).** Applied to every `/v1` request BEFORE the API key is checked, keyed on the caller's IP address: - **600 requests/minute** per IP - a flood ceiling, `429 rate_limit_error` / `rate_limited`. - **20 failed authentications per 15 minutes** per IP - a key-guessing ceiling. Only responses that are `401` (missing/invalid/revoked key) count against this ceiling; a `403` from a valid key that simply lacks a scope does not. `429 rate_limit_error` / `too_many_failed_attempts`. Both ceilings send `Retry-After` (seconds). 2. **Per-key, per-bucket limiter (post-authentication).** Documented per endpoint (see each operation's `429` response and the `rate_limit` field on the API Key resource) - e.g. 60/min default, 120/min for transactions, plus the notification-broadcast and lookup-filter buckets described on their own endpoints. ### Rate-limit response headers Every rate-limited response carries the legacy `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` family (the last is an **epoch timestamp**) AND the IETF standards-track headers, side by side: - `RateLimit-Policy: "";q=;w=` - the static policy for the bucket that was hit. - `RateLimit: "";r=;t=` - live state. **`t` is a DURATION (seconds remaining), not the epoch timestamp `X-RateLimit-Reset` carries - the two are never the same value.** version: 1.0.0 servers: - url: https://api.vexioncards.one description: Production - url: https://migration.api.vexioncards.one description: Sandbox security: - apiKey: [] tags: - name: Customers - name: Cards - name: Transactions - name: Notifications - name: Locations - name: Products - name: API keys - name: Organization - name: Webhook endpoints - name: Events - name: Custom fields - name: Team members - name: Icons paths: /v1/icons: get: tags: - Icons summary: List icons description: >- Browse the VEXiON cards 3D icon library. 10,000+ icons across 23 categories (Animals, Food & Drink, Technology & Media, etc.) for use as stamp_icon_url on stamp cards or pattern_icon_urls[] on non-stamp cards. **Scope: none required.** The catalog is identical for every organization - curated centrally by VEXiON, containing no organization data - so any authenticated key may read it regardless of its scopes. WHEN to use: - Building a custom icon picker UI in your dashboard - Letting end-customers pick icons for personalization - Discovering icons for specific card designs HOW it works: - Cursor-paginated (default 25, max 100 per page - the same bounds as every other list endpoint) - Ordered by `slug` ascending, NOT newest-first: this is a static catalog with no `created_at` - Filter by category (23 fixed categories returned in response for client-side UI) - Search by free text across icon title + tags (case-insensitive partial match) - Returns image_url directly usable in Card.design.stamp_icon_url or pattern_icon_urls GOTCHAS: - The library is static (curated by VEXiON). Partners cannot add custom icons via this endpoint. - Partners CAN still pass custom URLs to stamp_icon_url / pattern_icon_urls (uploaded to their own CDN). This endpoint just exposes our library. - Heavy caching is fine - the catalog rarely changes (new icons added quarterly). operationId: listIcons parameters: - name: category in: query description: >- Filter by category. Returns only icons in that category. Omit to include all categories. required: false example: Food & Drink schema: type: string enum: - Animals - Countries - Education & Learning - Entertainment & Leisure - Events - Everyday Life - Fantasy & Imagination - Fashion & Style - Flags - Food & Drink - Health & Wellness - Historical Figures - History & Culture - Hobbies - Interface & Symbols - Nature & Outdoors - Places & Structures - Professions - Space & Science - Sports - Technology & Media - Vehicles & Transport - Work & Industry - name: search in: query description: >- Free-text search across title + tags. Case-insensitive partial match. required: false example: coffee schema: type: string maxLength: 100 - name: limit in: query description: Items per page (1-100, Default 25). required: false example: 50 schema: type: integer minimum: 1 maximum: 100 default: 25 - name: starting_after in: query description: >- Cursor: slug of the last icon on the previous page. Numeric offset or page parameters are not supported; cursors are the only supported paging mechanism. required: false example: coffee-cup schema: type: string responses: '200': description: Paginated icon list. content: application/json: schema: $ref: '#/components/schemas/IconList' example: object: list data: - object: icon slug: coffee-cup title: Coffee Cup category: Food & Drink tags: - drink - beverage - cafe image_url: >- https://stamp-icons.s3.eu-central-1.amazonaws.com/coffee-cup.png added_on: '2025-05-15' - object: icon slug: croissant title: Croissant category: Food & Drink tags: - bakery - pastry - breakfast image_url: >- https://stamp-icons.s3.eu-central-1.amazonaws.com/croissant.png added_on: '2025-05-15' - object: icon slug: donut title: Donut category: Food & Drink tags: - dessert - sweet - breakfast image_url: >- https://stamp-icons.s3.eu-central-1.amazonaws.com/donut.png added_on: '2025-05-15' has_more: true total_count: 487 categories: - Animals - Countries - Education & Learning - Entertainment & Leisure - Events - Everyday Life - Fantasy & Imagination - Fashion & Style - Flags - Food & Drink - Health & Wellness - Historical Figures - History & Culture - Hobbies - Interface & Symbols - Nature & Outdoors - Places & Structures - Professions - Space & Science - Sports - Technology & Media - Vehicles & Transport - Work & Industry url: /v1/icons examples: Food drink first page: summary: Food drink first page value: object: list data: - object: icon slug: coffee-cup title: Coffee Cup category: Food & Drink tags: - drink - beverage - cafe image_url: >- https://stamp-icons.s3.eu-central-1.amazonaws.com/coffee-cup.png added_on: '2025-05-15' - object: icon slug: croissant title: Croissant category: Food & Drink tags: - bakery - pastry - breakfast image_url: >- https://stamp-icons.s3.eu-central-1.amazonaws.com/croissant.png added_on: '2025-05-15' - object: icon slug: donut title: Donut category: Food & Drink tags: - dessert - sweet - breakfast image_url: >- https://stamp-icons.s3.eu-central-1.amazonaws.com/donut.png added_on: '2025-05-15' has_more: true total_count: 487 categories: - Animals - Countries - Education & Learning - Entertainment & Leisure - Events - Everyday Life - Fantasy & Imagination - Fashion & Style - Flags - Food & Drink - Health & Wellness - Historical Figures - History & Culture - Hobbies - Interface & Symbols - Nature & Outdoors - Places & Structures - Professions - Space & Science - Sports - Technology & Media - Vehicles & Transport - Work & Industry url: /v1/icons headers: {} '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: invalid_request_error code: invalid_query_parameter message: >- Invalid category. Allowed: Animals, Countries, Entertainment & Leisure, Everyday Life, Flags, Food & Drink, Hobbies, Interface & Symbols, Nature & Outdoors, Places & Structures, Professions, Space & Science, Sports, Technology & Media, Vehicles & Transport. param: category doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#invalid_query_parameter request_id: req_4d8b1e2f9c3a5 examples: Http 400: summary: Http 400 value: error: type: invalid_request_error code: invalid_query_parameter message: >- Invalid category. Allowed: Animals, Countries, Entertainment & Leisure, Everyday Life, Flags, Food & Drink, Hobbies, Interface & Symbols, Nature & Outdoors, Places & Structures, Professions, Space & Science, Sports, Technology & Media, Vehicles & Transport. param: category doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#invalid_query_parameter request_id: req_4d8b1e2f9c3a5 headers: {} '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: authentication_error code: missing_api_key message: >- Authorization header is required. Send 'Authorization: Bearer vxn_sk_...'. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#missing_api_key request_id: req_7c2a9f1d4e6b3 examples: Http 401: summary: Http 401 value: error: type: authentication_error code: missing_api_key message: >- Authorization header is required. Send 'Authorization: Bearer vxn_sk_...'. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#missing_api_key request_id: req_7c2a9f1d4e6b3 API key revoked: summary: API key revoked value: error: type: authentication_error code: api_key_revoked message: >- This API key has been revoked. Mint a new key from the dashboard at https://app.vexioncards.one/settings/developers. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#api_key_revoked request_id: req_wMkZTJCycV3Pe4m3caTTWgGZxQ API key paused: summary: API key paused value: error: type: authentication_error code: api_key_paused message: This API key is paused. Resume it from the dashboard. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#api_key_paused request_id: req_n3FAfvGqbRCWK3899NGcK3ReAE headers: {} '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: rate_limit_error code: rate_limited message: Too many requests. Try again in 5 seconds. retry_after: 5 doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#rate_limited request_id: req_2c8e4f6a9d1b3 examples: Http 429: summary: Http 429 value: error: type: rate_limit_error code: rate_limited message: Too many requests. Try again in 5 seconds. retry_after: 5 doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#rate_limited request_id: req_2c8e4f6a9d1b3 headers: {} '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: api_error code: internal_error message: An internal error occurred. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#internal_error request_id: req_5f8b2c4a9e1d3 examples: Http 500: summary: Http 500 value: error: type: api_error code: internal_error message: An internal error occurred. doc_url: >- https://vexioncards.mintlify.site/api-reference/errors#internal_error request_id: req_5f8b2c4a9e1d3 headers: {} deprecated: false components: schemas: IconList: type: object required: - object - data - has_more description: Cursor-paginated list of icons from the VEXiON 3D icon library. properties: object: type: string enum: - list description: Always `"list"`. data: type: array items: $ref: '#/components/schemas/Icon' description: Icon objects for this page. has_more: type: boolean description: True when more icons match after this page. next_cursor: type: - string - 'null' description: >- Cursor for the next page **in the direction you are already paging**, or `null` when this page ends the collection. `has_more: true` always comes with a non-null `next_cursor`. Feed it back to the SAME parameter you used: `starting_after` when paging forward (the default), or `ending_before` when paging backward. Treat it as opaque and do not parse it. You no longer need to take the last object's `id` yourself. That still works and is unchanged, but deriving the cursor from the page put the burden of knowing the sort direction on you, and it broke silently on any endpoint whose cursor is not the object id. example: cus_iofv5j4hn6bphinmmyat27tc5y total_count: type: integer description: >- Total icons matching the query (across all pages). ~10,000 unfiltered. example: 10000 categories: type: array items: type: string enum: - Animals - Countries - Education & Learning - Entertainment & Leisure - Events - Everyday Life - Fantasy & Imagination - Fashion & Style - Flags - Food & Drink - Health & Wellness - Historical Figures - History & Culture - Hobbies - Interface & Symbols - Nature & Outdoors - Places & Structures - Professions - Space & Science - Sports - Technology & Media - Vehicles & Transport - Work & Industry description: >- The distinct category vocabulary - useful to build a filter dropdown. example: - Animals - Countries - Education & Learning - Entertainment & Leisure - Events - Everyday Life - Fantasy & Imagination - Fashion & Style - Flags - Food & Drink - Health & Wellness - Historical Figures - History & Culture - Hobbies - Interface & Symbols - Nature & Outdoors - Places & Structures - Professions - Space & Science - Sports - Technology & Media - Vehicles & Transport - Work & Industry url: type: string description: Stable collection URL. Error: type: object required: - error properties: error: type: object required: - type - code - message properties: type: type: string enum: - invalid_request_error - authentication_error - permission_error - not_found_error - rate_limit_error - idempotency_error - api_error code: type: string message: type: string retry_after: type: integer description: >- Seconds to wait before retrying. Present on rate-limit (429) and idempotency-key-in-use (409) errors; mirrors the `Retry-After` HTTP header. Absent on error types that carry no retry guidance. example: 5 param: type: - string - 'null' request_id: type: string doc_url: type: string format: uri field_errors: type: array description: >- Per-field errors on a 422. At most 100 entries: a request with more errors gets the first 100. items: type: object properties: param: type: string code: type: string message: type: string expected_currency: type: string description: >- On `currency_mismatch`: the business currency the request must use. Absent on every other field error. description: >- The error payload: type (category), code (machine-readable), message (human-readable), retry_after (seconds, on rate-limit/idempotency-in-use errors only), param (offending field), request_id, doc_url, field_errors[]. description: >- Standard error envelope. Branch on `error.code`; include `error.request_id` in support requests. See the Errors guide. Icon: type: object required: - object - slug - title - category - image_url description: >- An icon from the VEXiON cards 3D icon library. 10,000+ icons across 23 categories - use them as stamp_icon_url or pattern_icon_urls in card designs. properties: object: type: string enum: - icon description: Always 'icon'. Type discriminator. slug: type: string pattern: ^[a-z0-9_-]+$ description: >- Unique URL-safe identifier (lowercase, hyphens/underscores). Used as the filename in image_url. example: coffee-cup title: type: string description: Human-readable title. example: Coffee Cup category: type: string description: >- Category for grouping/filtering in icon pickers. Open set - the library grows; filter values come from the live catalog (`GET /v1/icons` returns each icon's category; common ones: food, drinks, beauty, sport, retail, ...). example: Food & Drink tags: type: array items: type: string description: Search keywords associated with this icon. example: - drink - beverage - cafe image_url: type: string format: uri description: >- Direct CDN URL to the icon image (PNG, transparent background, 3D style), hosted on our trusted https CDN. Use this value as stamp_icon_url or pattern_icon_urls[] on Card design. Because this URL already lives on our own storage, submitting it back as stamp_icon_url / pattern_icon_urls[] / etc. is recognized as already-ours and is never re-ingested. example: https://stamp-icons.s3.eu-central-1.amazonaws.com/coffee-cup.png added_on: type: string format: date description: Date the icon was added to the library (YYYY-MM-DD). example: '2025-05-15' securitySchemes: apiKey: type: http scheme: bearer description: >- Your secret API key as a Bearer token: `Authorization: Bearer vxn_sk_...`. Keys are created and scoped in the dashboard - see [Authentication](/api-reference/introduction#authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.