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

# Search categories

> Search Etsy's seller categories by name and get each one's full path. Use a category's ID to filter product research.

**Cost:** Free.

```bash
curl -G "https://api.alura.io/v1/etsy/categories" \
  -H "Authorization: Bearer $ALURA_API_KEY" \
  --data-urlencode "q=kitchen mugs"
```

A category matches when every word of `q` is in its name or its path (the names above it), in any letter case, also inside a longer word. Without `q`, you get the top-level categories.

> [accordion] How results are ordered
>
> Best matches first: the name is exactly `q`, then it starts with `q`, then it contains `q`, then it holds every word, then the rest. Within each group, shallower categories come first, then by name.

Pass a category's `id` as `category_id` to [Search products](https://docs.alura.io/api-reference/research/products/search.md): it covers every category under it too. For a category's parent and subcategories, use [Get category](https://docs.alura.io/api-reference/etsy/categories/get.md).


## OpenAPI

````yaml /openapi.json get /v1/etsy/categories
openapi: 3.1.0
info:
  title: Alura API
  version: 1.0.0
  description: Etsy market research for scripts and AI assistants.
servers:
  - url: https://api.alura.io
security:
  - apiKey: []
paths:
  /v1/etsy/categories:
    get:
      summary: Search categories
      description: >-
        Finds Etsy categories that hold every word of `q` in their name or path
        (in any letter case, also inside a longer word), each with its full
        path. Best matches first: the name is `q`, then starts with it, contains
        it, holds every word, then the rest; within each, shallower categories
        first, then by name. Without `q`, lists the top-level categories.


        Cost: free.
      operationId: etsy.categories.search
      parameters:
        - name: q
          in: query
          required: false
          description: >-
            Words to find, for example `mugs` or `kitchen mugs`. A category
            matches when every word appears, in any letter case and also inside
            a longer word, in its name or in its path (the names above it).
            Without it, the top-level categories are listed.
          schema:
            description: >-
              Words to find, for example `mugs` or `kitchen mugs`. A category
              matches when every word appears, in any letter case and also
              inside a longer word, in its name or in its path (the names above
              it). Without it, the top-level categories are listed.
            type: string
            minLength: 1
            maxLength: 100
            example: mugs
        - name: limit
          in: query
          required: false
          description: 'Page size: default 25, at most 100.'
          schema:
            type: integer
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          required: false
          description: >-
            The `next_cursor` of the previous page. Bound to the query, the
            workspace and the key.
          schema:
            type: string
        - name: fields
          in: query
          required: false
          description: >-
            Comma-separated dotted paths to return; `id`, `object` and `as_of`
            always come back.
          schema:
            type: string
      responses:
        '200':
          description: OK
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            Alura-Credits-Cost:
              $ref: '#/components/headers/Alura-Credits-Cost'
            Alura-Credits-Remaining:
              $ref: '#/components/headers/Alura-Credits-Remaining'
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    const: list
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        object:
                          type: string
                          const: category
                        id:
                          type: string
                          description: Etsy seller-taxonomy ID, as a string.
                        name:
                          type: string
                          description: The category's name, as Etsy writes it.
                        path:
                          type: array
                          items:
                            type: string
                          description: Names from the top level down to this category.
                      required:
                        - object
                        - id
                        - name
                        - path
                      additionalProperties: false
                  has_more:
                    type: boolean
                  next_cursor:
                    type:
                      - string
                      - 'null'
                  total:
                    type: object
                    properties:
                      value:
                        type: integer
                      relation:
                        type: string
                        enum:
                          - eq
                          - gte
                    required:
                      - value
                      - relation
                    additionalProperties: false
                required:
                  - object
                  - data
                  - has_more
                  - next_cursor
                  - total
                additionalProperties: false
              example:
                object: list
                data:
                  - object: category
                    id: '1062'
                    name: Mugs
                    path:
                      - Home & Living
                      - Kitchen & Dining
                      - Drink & Barware
                      - Drinkware
                      - Mugs
                  - object: category
                    id: '11275'
                    name: Travel Mugs
                    path:
                      - Home & Living
                      - Kitchen & Dining
                      - Drink & Barware
                      - Drinkware
                      - Travel Mugs
                has_more: false
                next_cursor: null
                total:
                  value: 2
                  relation: eq
        '400':
          $ref: '#/components/responses/Problem400'
        '401':
          $ref: '#/components/responses/Problem401'
        '402':
          $ref: '#/components/responses/Problem402'
        '403':
          $ref: '#/components/responses/Problem403'
        '404':
          $ref: '#/components/responses/Problem404'
        '405':
          $ref: '#/components/responses/Problem405'
        '429':
          $ref: '#/components/responses/Problem429'
        '500':
          $ref: '#/components/responses/Problem500'
        '503':
          $ref: '#/components/responses/Problem503'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl "https://api.alura.io/v1/etsy/categories?q=mugs" \
              -H "Authorization: Bearer $ALURA_API_KEY"
        - lang: typescript
          label: TypeScript
          source: >-
            const res = await
            fetch('https://api.alura.io/v1/etsy/categories?q=mugs', {
              headers: {
                Authorization: `Bearer ${process.env.ALURA_API_KEY}`,
              },
            });

            console.log(await res.json());
        - lang: python
          label: Python
          source: |-
            import json
            import os
            import urllib.request

            request = urllib.request.Request(
                "https://api.alura.io/v1/etsy/categories?q=mugs",
                headers={
                    "Authorization": f"Bearer {os.environ['ALURA_API_KEY']}",
                },
            )
            with urllib.request.urlopen(request) as response:
                print(json.load(response))
components:
  headers:
    Request-Id:
      description: '`req_` + ULID; quote it when reporting a problem.'
      schema:
        type: string
    Alura-Credits-Cost:
      description: API credits this call cost.
      schema:
        type: integer
    Alura-Credits-Remaining:
      description: >-
        API credits left in the workspace's monthly allowance, counting calls
        still in flight. Absent when it cannot be read right now.
      schema:
        type: integer
  responses:
    Problem400:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/invalid_request
            title: Invalid request
            status: 400
            code: invalid_request
            detail: Invalid request
            suggestion: Fix the request as the detail says, then send it again.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem401:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/unauthorized
            title: Unauthorized
            status: 401
            code: unauthorized
            detail: Unauthorized
            suggestion: 'Send a valid API key as `Authorization: Bearer alura_sk_...`.'
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem402:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/credits_exhausted
            title: API credits exhausted
            status: 402
            code: credits_exhausted
            detail: API credits exhausted
            suggestion: Upgrade the plan or wait for the monthly reset.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem403:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/plan_required
            title: Plan required
            status: 403
            code: plan_required
            detail: Plan required
            suggestion: Upgrade the workspace plan to use this operation.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem404:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/not_found
            title: Not found
            status: 404
            code: not_found
            detail: Not found
            suggestion: Check the ID, or search for it first.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem405:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/method_not_allowed
            title: Method not allowed
            status: 405
            code: method_not_allowed
            detail: Method not allowed
            suggestion: Use one of the methods in the Allow header.
            retryable: false
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem429:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/rate_limited
            title: Rate limited
            status: 429
            code: rate_limited
            detail: Rate limited
            suggestion: Wait for Retry-After, then retry.
            retryable: true
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem500:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/internal_error
            title: Internal error
            status: 500
            code: internal_error
            detail: Internal error
            suggestion: Retry; if it keeps failing, report the request_id.
            retryable: true
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
    Problem503:
      description: Error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://docs.alura.io/errors/credits_unavailable
            title: API credits unavailable
            status: 503
            code: credits_unavailable
            detail: API credits unavailable
            suggestion: Retry shortly.
            retryable: true
            request_id: req_01JQ5W3H8M2N4P6R8T0V2X4Z6B
  schemas:
    Problem:
      type: object
      description: RFC 9457 problem details.
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: A code from the error catalog; new codes may be added.
          x-extensible-enum:
            - invalid_request
            - unknown_parameter
            - invalid_cursor
            - cursor_window_exceeded
            - invalid_reference
            - id_type_mismatch
            - invalid_keyword
            - shop_id_required
            - listing_not_publishable
            - sales_window_not_covered
            - unauthorized
            - credits_exhausted
            - plan_required
            - insufficient_scope
            - workspace_required
            - workspace_locked
            - your_shop_unavailable
            - writes_suspended
            - browser_refused
            - role_required
            - impersonation_refused
            - recent_sign_in_required
            - etsy_scope_required
            - etsy_partner_required
            - not_found
            - not_collected
            - not_found_on_etsy
            - shop_opted_out
            - method_not_allowed
            - conflict
            - key_limit_reached
            - reconnect_required
            - settings_not_fetched
            - listing_busy
            - settings_busy
            - shop_create_busy
            - idempotency_partial_unverifiable
            - listing_has_variations
            - changed_since
            - change_not_revertable
            - listing_in_ab_test
            - activation_skipped
            - idempotency_processing
            - confirmation_required
            - test_shop_active_cap
            - write_outcome_unknown
            - unprocessable
            - listing_removed_on_etsy
            - endpoint_removed
            - rate_limited
            - throttled
            - daily_credit_cap_exceeded
            - credits_reserved
            - fetch_limit_reached
            - write_rate_limited
            - sync_cooldown
            - shop_write_budget_exhausted
            - internal_error
            - write_misconfigured
            - upstream_unavailable
            - credits_unavailable
            - service_unavailable
            - fetch_unavailable
            - create_lock_unavailable
            - writes_paused
            - etsy_capacity
            - upstream_timeout
        detail:
          type: string
        suggestion:
          type: string
        retryable:
          type: boolean
        request_id:
          type: string
        upgrade_url:
          type: string
          format: uri
          description: 'credits_exhausted and plan_required: where to upgrade the plan.'
        credits_needed:
          type: integer
          description: 'API credit refusals: what the call needed.'
        credits_remaining:
          type: integer
          description: >-
            API credit refusals: what is left (of the month, or of the day for
            daily_credit_cap_exceeded).
        resets_at:
          type: string
          format: date-time
          description: >-
            credits_exhausted and daily_credit_cap_exceeded: when the limit
            resets.
      required:
        - type
        - title
        - status
        - code
        - detail
        - suggestion
        - retryable
        - request_id
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'An API key: `Authorization: Bearer alura_sk_...`.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.