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

# Get v1dataforseocatalogcategories



## OpenAPI

````yaml https://api.surnex.io/.well-known/openapi.json get /v1/dataforseo/catalog/categories
openapi: 3.1.0
info:
  title: Surnex API
  version: 0.2.0
servers:
  - url: https://api.surnex.io
security: []
paths:
  /v1/dataforseo/catalog/categories:
    get:
      tags:
        - v1
      parameters:
        - schema:
            anyOf:
              - type: boolean
              - type: string
                enum:
                  - 'true'
              - type: string
                enum:
                  - 'false'
            default: true
          required: false
          name: discover
          in: query
        - schema:
            type: string
            enum:
              - static
              - discovered
              - mixed
          required: false
          name: discovery_source
          in: query
        - schema:
            type: string
            minLength: 1
            maxLength: 128
          required: false
          name: search
          in: query
        - schema:
            anyOf:
              - type: boolean
              - type: string
                enum:
                  - 'true'
              - type: string
                enum:
                  - 'false'
          required: false
          name: refresh_discovery
          in: query
      responses:
        '200':
          description: >-
            Deterministic category buckets for catalog services. Groups can be
            consumed directly by UI sections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_at:
                    type: string
                  discovery_context:
                    type: object
                    properties:
                      requested_discovery:
                        type: boolean
                      force_refresh_requested:
                        type: boolean
                      source:
                        type: string
                        enum:
                          - none
                          - cache
                          - provider
                          - mixed
                      discovered_at:
                        type:
                          - string
                          - 'null'
                      cache_key:
                        type: string
                      cache_ttl_seconds:
                        type: integer
                        exclusiveMinimum: 0
                      cache_available:
                        type: boolean
                      cache_hit:
                        type: boolean
                      provider_calls:
                        type: integer
                        minimum: 0
                    required:
                      - requested_discovery
                      - force_refresh_requested
                      - source
                      - discovered_at
                      - cache_key
                      - cache_ttl_seconds
                      - cache_available
                      - cache_hit
                      - provider_calls
                  categories:
                    type: array
                    items:
                      type: object
                      properties:
                        category:
                          type: string
                          minLength: 1
                          description: Service category used for grouping and filtering
                        service_count:
                          type: integer
                          minimum: 0
                        operation_count:
                          type: integer
                          minimum: 0
                        services:
                          type: array
                          items:
                            type: string
                        by_discovery_source:
                          type: object
                          properties:
                            static:
                              type: integer
                              minimum: 0
                            discovered:
                              type: integer
                              minimum: 0
                            mixed:
                              type: integer
                              minimum: 0
                          required:
                            - static
                            - discovered
                            - mixed
                      required:
                        - category
                        - service_count
                        - operation_count
                        - services
                        - by_discovery_source
                  total_categories:
                    type: integer
                    minimum: 0
                  total_services:
                    type: integer
                    minimum: 0
                  total_operations:
                    type: integer
                    minimum: 0
                  supports_custom_paths:
                    type: boolean
                  supports_any_dataforseo_path:
                    type: boolean
                required:
                  - generated_at
                  - discovery_context
                  - categories
                  - total_categories
                  - total_services
                  - total_operations
                  - supports_custom_paths
                  - supports_any_dataforseo_path
              examples:
                categories:
                  value:
                    generated_at: '2026-02-24T00:00:00Z'
                    discovery_context:
                      requested_discovery: false
                      force_refresh_requested: false
                      source: none
                      discovered_at: null
                      cache_key: dataforseo:catalog:discovered:v1
                      cache_ttl_seconds: 900
                      cache_available: false
                      cache_hit: false
                      provider_calls: 0
                    total_categories: 3
                    total_services: 3
                    total_operations: 7
                    categories:
                      - category: ai_visibility
                        service_count: 1
                        operation_count: 2
                        services:
                          - ai_optimization
                        by_discovery_source:
                          static: 1
                          discovered: 0
                          mixed: 0
                      - category: keyword_research
                        service_count: 1
                        operation_count: 2
                        services:
                          - keywords_data
                        by_discovery_source:
                          static: 1
                          discovered: 0
                          mixed: 0
                      - category: serp
                        service_count: 1
                        operation_count: 3
                        services:
                          - serp
                        by_discovery_source:
                          static: 1
                          discovered: 0
                          mixed: 0
                    supports_custom_paths: true
                    supports_any_dataforseo_path: true
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                      details:
                        type: object
                        properties: {}
                        default: {}
                        additionalProperties: {}
                    required:
                      - code
                      - message
                      - request_id
                required:
                  - error
                description: ErrorResponse
              examples:
                badRequest:
                  value:
                    error:
                      code: VALIDATION_ERROR
                      message: Invalid request
                      request_id: req_123
                      details:
                        issues:
                          - path:
                              - discovery_source
                            message: >-
                              Invalid enum value. Expected static | discovered |
                              mixed
                            code: invalid_enum_value
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                      details:
                        type: object
                        properties: {}
                        default: {}
                        additionalProperties: {}
                    required:
                      - code
                      - message
                      - request_id
                required:
                  - error
                description: ErrorResponse
              examples:
                unauthorized:
                  value:
                    error:
                      code: UNAUTHORIZED
                      message: Unauthorized
                      request_id: req_123
                      details:
                        reason: missing_or_invalid_api_key
        '502':
          description: Provider discovery failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      request_id:
                        type: string
                      details:
                        type: object
                        properties: {}
                        default: {}
                        additionalProperties: {}
                    required:
                      - code
                      - message
                      - request_id
                required:
                  - error
                description: ErrorResponse
              examples:
                providerUnavailable:
                  value:
                    error:
                      code: PROVIDER_ERROR
                      message: Failed to discover DataForSEO operations
                      request_id: req_123
                      details:
                        provider_error:
                          code: BAD_REQUEST
                          message: Discovery endpoint failed
      security:
        - bearerAuth: []
        - apiKeyAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'Authorization: Bearer sk_...'
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````