openapi: 3.1.0
info:
  title: Magento REST Authentication Categories API
  description: 'The Adobe Commerce (Magento) REST API provides a comprehensive set of endpoints for interacting with all major aspects of an e-commerce store, including catalog management, orders, customers, inventory, shipping, and payments. It supports three authentication mechanisms: OAuth 1.0a for third-party integrations, token-based authentication for mobile apps and administrators, and guest access for select public endpoints. The API follows REST conventions and returns JSON responses, enabling developers to build integrations, automate store operations, and power headless commerce storefronts. All endpoints are versioned under the /V1 prefix and support searchCriteria query parameters for filtering, sorting, and paginating collection responses.'
  version: '2.4'
  contact:
    name: Adobe Commerce Developer Support
    url: https://developer.adobe.com/commerce/webapi/rest/
  termsOfService: https://www.adobe.com/legal/terms.html
servers:
- url: https://{store_domain}/rest/{store_code}
  description: Production Server
  variables:
    store_domain:
      default: your-store.example.com
      description: The hostname of your Adobe Commerce store
    store_code:
      default: V1
      description: Store code followed by API version. Use "all" as store code for admin-scope operations, or the specific store view code for store-scoped operations. The V1 version path segment follows.
security:
- bearerAuth: []
tags:
- name: Categories
  description: Category tree management including creation, retrieval, update, and deletion of catalog categories and their product assignments.
paths:
  /V1/categories:
    get:
      operationId: listCategories
      summary: List categories
      description: Returns the full category tree starting from the specified root category. The response is a nested tree structure with each category containing its children. Use the rootCategoryId parameter to start from a specific category node, and the depth parameter to limit tree traversal depth.
      tags:
      - Categories
      parameters:
      - name: rootCategoryId
        in: query
        description: Root category ID to start the tree from. Defaults to the default root category.
        required: false
        schema:
          type: integer
      - name: depth
        in: query
        description: Maximum depth of the category tree to return.
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Category tree
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryTree'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCategory
      summary: Create a category
      description: Creates a new product category. The parent_id field determines where in the category tree the new category is placed. The position field controls sort order among sibling categories. Custom category attributes can be set via the custom_attributes array.
      tags:
      - Categories
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryRequest'
      responses:
        '200':
          description: Category created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /V1/categories/{categoryId}:
    get:
      operationId: getCategory
      summary: Get category by ID
      description: Retrieves a single category by its numeric identifier. Returns the category data including its name, path, parent ID, and custom attributes. Does not include the full subtree; use the list endpoint for tree traversal.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/categoryId'
      responses:
        '200':
          description: Category object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCategory
      summary: Update a category
      description: Updates an existing category identified by its numeric ID. Fields included in the request body overwrite existing values. Custom attributes in the custom_attributes array replace their corresponding stored values.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/categoryId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CategoryRequest'
      responses:
        '200':
          description: Updated category object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Category'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCategory
      summary: Delete a category
      description: Permanently deletes a category by its numeric ID. Products assigned only to the deleted category will not be deleted but may become uncategorized. Child categories of the deleted category are also deleted recursively.
      tags:
      - Categories
      parameters:
      - $ref: '#/components/parameters/categoryId'
      responses:
        '200':
          description: Category deleted successfully
          content:
            application/json:
              schema:
                type: boolean
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Category:
      type: object
      description: A product category in the catalog category tree.
      properties:
        id:
          type: integer
          description: Numeric category entity ID.
        parent_id:
          type: integer
          description: Numeric ID of the parent category.
        name:
          type: string
          description: Display name of the category.
        is_active:
          type: boolean
          description: Whether the category is active and visible in the storefront.
        position:
          type: integer
          description: Sort position among sibling categories.
        level:
          type: integer
          description: Depth level of the category in the tree (root = 1).
        children:
          type: string
          description: Comma-separated list of child category IDs.
        created_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the category was created.
        updated_at:
          type: string
          format: date-time
          description: ISO 8601 timestamp when the category was last updated.
        path:
          type: string
          description: Path string of category IDs from root to this category, separated by slashes.
        include_in_menu:
          type: boolean
          description: Whether this category appears in the navigation menu.
        custom_attributes:
          type: array
          description: Custom EAV attribute values for this category.
          items:
            $ref: '#/components/schemas/CustomAttribute'
    CustomAttribute:
      type: object
      description: A key-value pair representing a custom EAV attribute on a catalog entity.
      required:
      - attribute_code
      - value
      properties:
        attribute_code:
          type: string
          description: The unique attribute code identifier.
        value:
          description: The attribute value. Can be a string, integer, or array depending on the attribute type.
    CategoryTree:
      allOf:
      - $ref: '#/components/schemas/Category'
      - type: object
        properties:
          children_data:
            type: array
            description: Nested child category objects forming the category tree.
            items:
              $ref: '#/components/schemas/CategoryTree'
    CategoryRequest:
      type: object
      description: Request body for creating or updating a category.
      required:
      - category
      properties:
        category:
          $ref: '#/components/schemas/Category'
    Error:
      type: object
      description: Standard error response returned for 4xx and 5xx responses.
      properties:
        message:
          type: string
          description: Human-readable error message.
        parameters:
          type: array
          description: Additional error context parameters.
          items:
            type: object
  responses:
    Unauthorized:
      description: Unauthorized — missing or invalid authentication token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Bad request — invalid input parameters or request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found — the requested resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    categoryId:
      name: categoryId
      in: path
      description: The numeric category entity ID.
      required: true
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from the /V1/integration/admin/token or /V1/integration/customer/token endpoint. Include in the Authorization header as "Bearer {token}".
externalDocs:
  description: Adobe Commerce REST API Documentation
  url: https://developer.adobe.com/commerce/webapi/rest/