> ## Documentation Index > Fetch the complete documentation index at: https://docs.snappy.com/llms.txt > Use this file to discover all available pages before exploring further. # Get collection by ID > Use this endpoint to retrieve a single Collection's full metadata - name, description, cover image, thumbnails, rank, and provenance. Use this when rendering a Collection detail page before drilling into its Products via `GET /v3/collections/{collectionId}/products`. ###### Required path parameters - `collectionId` - the Collection identifier. ###### Optional query parameters - `filter[location]` - comma-separated ISO 3166-1 alpha-2 country codes. Thumbnails and `priceRange` use the first location. Defaults to `US`. - `filter[maxPrice]` - budget bucket selector that controls which thumbnail set is returned. - `fields` - comma-separated list of optional fields to include. One or more of `priceRange`, `updatedBy`, `createdVia`. ###### Required headers - `Snappy-Account-Id` - account scope. ###### Optional headers - `Snappy-Company-Id` - further scope to a specific Company within the Account. ###### Please note - Always returns `id`, `name`, `description`, `tags`, `media`, `coverImage`, `rank`, `createdBy`, `createdAt`, and `updatedAt`. The `fields` parameter *adds* the listed optional fields on top of these defaults. - Returns `404` (`404_PBLC_004`) if the Collection is not found **or** is not visible to the calling Account. The two cases are intentionally indistinguishable - visibility is treated as identical to non-existence to avoid leaking other Accounts' Collections. #### Permissions - Requires: `collections:read` ## OpenAPI ````yaml get /v3/collections/{collectionId} openapi: 3.0.3 info: title: Snappy Public API v3 version: 3.0.0 contact: name: Snappy Support email: info@snappy.com description: >- Welcome to the Snappy API reference documentation! You can use this API to integrate with Snappy and spread smiles to your employees/clients/customers and much more. So let's get started! servers: - url: https://api.snappy.com/public-api description: Base API URL - url: https://mtls-api.snappy.com/public-api description: >- ## mTLS URL You can also use mTLS to enhance your API security. To get your specific certificates please contact our support. Once you configure the certificated correctly, you need to also update endpoints to use the following secure api base URL: security: [] tags: - name: Products description: >- Use these endpoints to retrieve products and tags for building catalog and browse experiences in your UI. - name: Collections description: >- Use these endpoints to retrieve products within curated collections for marketplace and browse experiences. - name: Variants description: >- Use these endpoints to retrieve variants, variant pricing, and country availability for orderable product SKUs. - name: Billing Methods description: >- A **Billing Method** is the funding source attached to an **Account** - for example, a Purchase Order (PO), Invoice, Prepay deposit, or Credit Card. Use these endpoints to retrieve billing method details such as remaining balance, status, and expiration. - name: Accounts description: >- An **Account** is a sub-entity within a **Company**, used to organize campaigns and gift sends. Use these endpoints to list, retrieve, and create accounts. - name: API Keys description: >- Use these endpoints to manage API keys for programmatic access. Key management requires company owner privileges. - name: Orders description: >- Use these endpoints to place, retrieve, cancel, and validate orders and shipping addresses. paths: /v3/collections/{collectionId}: get: tags: - Collections summary: Get collection by ID description: >- Use this endpoint to retrieve a single Collection's full metadata - name, description, cover image, thumbnails, rank, and provenance. Use this when rendering a Collection detail page before drilling into its Products via `GET /v3/collections/{collectionId}/products`. ###### Required path parameters - `collectionId` - the Collection identifier. ###### Optional query parameters - `filter[location]` - comma-separated ISO 3166-1 alpha-2 country codes. Thumbnails and `priceRange` use the first location. Defaults to `US`. - `filter[maxPrice]` - budget bucket selector that controls which thumbnail set is returned. - `fields` - comma-separated list of optional fields to include. One or more of `priceRange`, `updatedBy`, `createdVia`. ###### Required headers - `Snappy-Account-Id` - account scope. ###### Optional headers - `Snappy-Company-Id` - further scope to a specific Company within the Account. ###### Please note - Always returns `id`, `name`, `description`, `tags`, `media`, `coverImage`, `rank`, `createdBy`, `createdAt`, and `updatedAt`. The `fields` parameter *adds* the listed optional fields on top of these defaults. - Returns `404` (`404_PBLC_004`) if the Collection is not found **or** is not visible to the calling Account. The two cases are intentionally indistinguishable - visibility is treated as identical to non-existence to avoid leaking other Accounts' Collections. #### Permissions - Requires: `collections:read` parameters: - schema: type: string pattern: ^[A-Za-z0-9]{8,}$ description: Collection identifier. example: abcdef12 required: true description: Collection identifier. name: collectionId in: path - schema: type: string pattern: ^([A-Z]{2})(,[A-Z]{2})*$ default: US description: >- Comma-separated ISO 3166-1 alpha-2 country codes. Thumbnails and budget data use the first location. example: US required: false description: >- Comma-separated ISO 3166-1 alpha-2 country codes. Thumbnails and budget data use the first location. name: filter[location] in: query - schema: type: number nullable: true minimum: 0 maximum: 99999 description: Budget bucket selector for thumbnails. example: 80 required: false description: Budget bucket selector for thumbnails. name: filter[maxPrice] in: query - schema: type: array items: type: string enum: - priceRange - createdVia description: 'Optional fields: `priceRange`, `createdVia`.' example: - priceRange required: false description: 'Optional fields: `priceRange`, `createdVia`.' name: fields in: query style: form explode: false - schema: type: string description: Account identifier. example: acc123456 required: true description: Account identifier. name: snappy-account-id in: header - schema: type: string description: Optional company identifier. example: cmp123456 required: false description: Optional company identifier. name: snappy-company-id in: header responses: '200': description: A single collection resource. content: application/json: schema: $ref: '#/components/schemas/GetCollectionByIdV3Response' '400': description: Bad Request - Invalid query parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' '404': description: Not Found - Collection not found or not visible. content: application/json: schema: $ref: '#/components/schemas/ErrorResponseV3' example: message: Collection not found. errorCode: 404_PBLC_004 security: - ApiKeyAuthentication: [] components: schemas: GetCollectionByIdV3Response: type: object properties: data: $ref: '#/components/schemas/CollectionByIdV3' required: - data description: Single collection response envelope. ErrorResponseV3: type: object properties: message: type: string description: Human-readable error message. example: Product not found. errorCode: type: string description: Structured error code. example: 404_PROD_001 errors: type: array items: type: object properties: message: type: string example: Product with id 'q1w2e3r4t5' was not found path: type: string description: Dot-separated path to the field that caused the error. example: pathParameters.productId errorCode: type: string example: 404_PROD_001 required: - message - path description: Optional field-level error details. required: - message - errorCode description: Standard v3 error envelope. CollectionByIdV3: allOf: - $ref: '#/components/schemas/CollectionV3' - type: object properties: description: type: string nullable: true createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - description - createdAt - updatedAt description: Collection resource. CollectionV3: type: object properties: id: type: string description: Collection identifier. example: 64a1234567890abcdef12345 name: type: string example: Birthday Gifts tags: type: array items: $ref: '#/components/schemas/CollectionTagV3' description: Collection type tags. media: type: array items: $ref: '#/components/schemas/MediaV3' description: Collection thumbnail images for the selected budget bucket. coverImage: allOf: - $ref: '#/components/schemas/MediaV3' - nullable: true description: B2B cover image. `null` when not set. rank: type: integer description: Display rank (lower = higher priority). example: 10 description: type: string nullable: true description: >- Returned when `fields` includes `description` (list) or always on by-id. priceRange: $ref: '#/components/schemas/CollectionPriceRangeV3' createdAt: type: string format: date-time description: >- Returned when `fields` includes `createdAt` (list) or always on by-id. updatedAt: type: string format: date-time description: >- Returned when `fields` includes `updatedAt` (list) or always on by-id. createdVia: type: string nullable: true description: >- Origin of collection creation. Returned when `fields` includes `createdVia`. example: dashboard required: - id - name - tags - media - coverImage - rank description: >- Collection summary. Optional fields depend on endpoint and `fields` parameter. CollectionTagV3: type: string enum: - gifts - swag - custom description: Collection type tag. example: gifts MediaV3: type: object properties: type: type: string enum: - image - video description: Media type. example: image src: type: string format: uri description: Media source URL. example: >- https://media.snappy.com/image/o1xc17wfbda6cl91hm0r6_picture-1.jpg?w=1000&h=1000&q=80&f=auto required: - type - src description: A media item for v3 endpoints. CollectionPriceRangeV3: type: object nullable: true properties: min: type: number example: 25 max: type: number example: 200 required: - min - max description: Min/max budget range for the first requested location. securitySchemes: ApiKeyAuthentication: type: apiKey in: header name: X-Api-Key description: |- ## Company Level Authentication Include your API key in the `X-Api-Key` header for every request: ``` X-Api-Key: YOUR_API_KEY ``` ````