> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merchkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List attribute definitions (schema discovery)

> The schema of an entity type: every attribute key, its data type, whether it is `writable` (formulas/inverse references are not), and the parsed `acceptable_values` for selects. Call this FIRST and cache it — entity `attributes` maps are sparse, so this is the canonical "what fields exist" answer. Optionally scope to a channel.



## OpenAPI

````yaml https://www.merchkit.com/api/v1/openapi get /attributes
openapi: 3.1.0
info:
  title: Merchkit API
  version: 1.0.0
  description: >-
    Operate your Merchkit PIM programmatically. Products, images, vendors,
    categories, and data sources are all "entities" in one uniform shape: system
    fields (`id`, `type`, `label`, `parent_id`, timestamps) at the top level and
    every customer-defined key — scalars AND references — in a sparse
    `attributes` map. References read as labeled stubs `{id, type, label}` and
    write as bare UUIDs or `{id}` objects ("write what you read"). UUIDs are the
    only path identifiers; find by your own key with a filter (`GET
    /products?filter[sku]=ARIA-DT-72`) or write by it with `POST
    /{resource}/upsert` and `/batch` (products, images, vendors, and categories
    only — sources have neither route; they are created by the async `POST
    /sources` job pipeline). Start every integration with `GET
    /attributes?type=product` to learn your keys. Completeness is per-channel.
    All errors share one envelope (see the `Error` schema). Authenticate with a
    workspace-scoped API key: `Authorization: Bearer mk_live_...`. See /llms.txt
    for an agent guide.
servers:
  - url: https://www.merchkit.com/api/v1
    description: Merchkit API v1
security:
  - ApiKeyAuth: []
paths:
  /attributes:
    get:
      summary: List attribute definitions (schema discovery)
      description: >-
        The schema of an entity type: every attribute key, its data type,
        whether it is `writable` (formulas/inverse references are not), and the
        parsed `acceptable_values` for selects. Call this FIRST and cache it —
        entity `attributes` maps are sparse, so this is the canonical "what
        fields exist" answer. Optionally scope to a channel.
      operationId: listAttributes
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum:
              - product
              - image
              - vendor
              - category
              - source
            default: product
          description: The entity type to describe.
        - name: channel
          in: query
          schema:
            type: string
          description: Restrict to one channel's attributes.
      responses:
        '200':
          description: Attribute definitions (not paginated).
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AttributeDefinition'
              example:
                data:
                  - id: a3d81c22-5f6e-4b09-8d17-c40a92e5b613
                    key: material
                    name: Material
                    entity_type: product
                    data_type: single_select_list
                    channel: null
                    is_primary: false
                    writable: true
                    acceptable_values:
                      - White Oak
                      - Smoked Oak
                      - Walnut
                    default_value: null
        '400':
          description: Invalid `type`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AttributeDefinition:
      type: object
      description: >-
        The discovery projection of an attribute definition (`GET /attributes`):
        what the key is, whether you may write it, and what values it accepts.
      required:
        - id
        - key
        - name
        - entity_type
        - data_type
        - channel
        - is_primary
        - writable
        - acceptable_values
        - default_value
      properties:
        id:
          type: string
          format: uuid
        key:
          type: string
          description: The key used in `attributes`, filters, and sorts.
        name:
          type: string
        entity_type:
          type: string
        data_type:
          type: string
        channel:
          type:
            - string
            - 'null'
          description: Set when the attribute is channel-scoped.
        is_primary:
          type: boolean
          description: The primary attribute supplies every entity's `label`.
        writable:
          type: boolean
          description: >-
            False for derived types (formula, inverse_reference,
            reference_lookup) — writes to them are rejected.
        acceptable_values:
          type: array
          items:
            type: string
          description: Parsed allowed values for selects; empty when unconstrained.
        default_value:
          type:
            - string
            - 'null'
      example:
        id: a3d81c22-5f6e-4b09-8d17-c40a92e5b613
        key: material
        name: Material
        entity_type: product
        data_type: single_select_list
        channel: null
        is_primary: false
        writable: true
        acceptable_values:
          - White Oak
          - Smoked Oak
          - Walnut
        default_value: null
    Error:
      type: object
      description: >-
        The one error envelope every non-2xx response uses. `documentation_url`
        links to the code's section of the error docs.
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - is_retriable
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - insufficient_scope
                - forbidden
                - not_found
                - validation_failed
                - rate_limited
                - conflict
                - internal_error
            message:
              type: string
            documentation_url:
              type: string
              format: uri
              description: https://docs.merchkit.com/developers/errors#<code>
            is_retriable:
              type: boolean
              description: >-
                Only `rate_limited` and `internal_error` are retriable.
                Deterministic client errors (validation, not-found, conflict)
                return a 4xx and are never retriable.
            retry_after_seconds:
              type:
                - integer
                - 'null'
            alternative_action:
              type: string
              description: What to do instead, when there is a better call.
            request_id:
              type: string
            field_errors:
              type: array
              items:
                $ref: '#/components/schemas/FieldError'
      example:
        error:
          code: validation_failed
          message: 'Unknown attribute key(s): colour.'
          documentation_url: https://docs.merchkit.com/developers/errors#validation_failed
          is_retriable: false
          retry_after_seconds: null
          alternative_action: List valid attribute keys via GET /v1/attributes?type=product.
          request_id: req_01j9x2k8
          field_errors:
            - field: colour
              issue: not_a_defined_attribute
    FieldError:
      type: object
      required:
        - field
        - issue
      properties:
        field:
          type: string
        issue:
          type: string
          description: Machine-readable issue code, e.g. `not_a_defined_attribute`.
        acceptable_values:
          type: array
          items:
            type: string
          description: 'For select-value violations: the allowed values.'
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Workspace-scoped API key. Available scopes:

        - `read:products`: List and read products, including variants,
        references, and completeness.

        - `write:products`: Create, update, and upsert products and their
        attribute values.

        - `delete:products`: Delete products.

        - `read:images`: List and read images.

        - `write:images`: Create, update, and upsert images and their attribute
        values.

        - `delete:images`: Delete images.

        - `read:vendors`: List and read vendors.

        - `write:vendors`: Create, update, and upsert vendors and their
        attribute values.

        - `delete:vendors`: Delete vendors.

        - `read:categories`: List and read categories.

        - `write:categories`: Create, update, and upsert categories and their
        attribute values.

        - `delete:categories`: Delete categories.

        - `read:sources`: List and read data sources, including scraped content.

        - `write:sources`: Create data sources (triggers processing) and update
        their attribute values.

        - `delete:sources`: Delete data sources.

        - `read:attributes`: List and read attribute definitions.

        - `write:attributes`: Create and update attribute definitions.

        - `read:views`: List and read saved grid views (MCP surface).

        - `write:views`: Create and update grid views (MCP surface).

        - `read:channels`: Read the enabled channel catalog.

        - `read:events`: Read the workspace change feed and per-entity events.

        - `read:jobs`: List and poll asynchronous job status.

````