> ## 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 v1providers catalog ## OpenAPI ````yaml https://api.surnex.io/.well-known/openapi.json get /v1/providers/{provider}/catalog openapi: 3.1.0 info: title: Surnex API version: 0.2.0 servers: - url: https://api.surnex.io security: [] paths: /v1/providers/{provider}/catalog: get: tags: - v1 parameters: - schema: type: string minLength: 1 required: true name: provider in: path - schema: type: string minLength: 1 required: false name: service in: query - schema: anyOf: - type: boolean - type: string enum: - 'true' - type: string enum: - 'false' 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: type: string minLength: 1 description: Service category used for grouping and filtering required: false description: Service category used for grouping and filtering name: category in: query - schema: anyOf: - type: boolean - type: string enum: - 'true' - type: string enum: - 'false' required: false name: refresh_discovery in: query - schema: type: string enum: - discovery_source description: >- Optional grouping key for response sections. When set, services are additionally bucketed into `groups` without removing `services`. Group keys are emitted in this order when present: `static`, `discovered`, `mixed`. required: false description: >- Optional grouping key for response sections. When set, services are additionally bucketed into `groups` without removing `services`. Group keys are emitted in this order when present: `static`, `discovered`, `mixed`. name: group_by in: query responses: '200': description: Provider catalog for a specific Surnex provider. content: application/json: schema: type: object properties: provider: type: string minLength: 1 catalog: anyOf: - type: object properties: services: type: array items: type: object properties: service: type: string minLength: 1 title: type: string minLength: 1 category: type: string minLength: 1 description: >- Service category used for grouping and filtering description: type: string examples: type: array items: type: string discovery_source: type: string enum: - static - discovered - mixed description: CatalogDiscoverySource operations: type: array items: type: object properties: service: type: string minLength: 1 operation_path: type: string minLength: 1 path_template: type: string minLength: 1 method: type: string enum: - GET - POST description: HTTPMethod mode: type: string enum: - live - task_post - task_get - tasks_ready - tasks_fixed description: DataForSeoOperationMode description: type: string discovery_source: type: string enum: - static - discovered required: - service - operation_path - path_template - method - mode - description required: - service - title - category - description - examples - operations total_services: type: integer minimum: 0 groups: type: object additionalProperties: type: array items: type: object properties: service: type: string minLength: 1 title: type: string minLength: 1 category: type: string minLength: 1 description: >- Service category used for grouping and filtering description: type: string examples: type: array items: type: string discovery_source: type: string enum: - static - discovered - mixed description: CatalogDiscoverySource operations: type: array items: type: object properties: service: type: string minLength: 1 operation_path: type: string minLength: 1 path_template: type: string minLength: 1 method: type: string enum: - GET - POST description: HTTPMethod mode: type: string enum: - live - task_post - task_get - tasks_ready - tasks_fixed description: DataForSeoOperationMode description: type: string discovery_source: type: string enum: - static - discovered required: - service - operation_path - path_template - method - mode - description required: - service - title - category - description - examples - operations description: >- Grouped service buckets keyed by selected `group_by` value. Omitted when `group_by` is not requested. supports_custom_paths: type: boolean supports_any_dataforseo_path: type: boolean 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 required: - services - total_services - supports_custom_paths - supports_any_dataforseo_path - generated_at - discovery_context - type: object additionalProperties: {} required: - provider - catalog description: SurnexProviderCatalogResponse examples: catalog: value: provider: dataforseo catalog: services: - service: serp category: serp discovery_source: mixed title: SERP API description: >- Search engine results across web and vertical engines examples: - google - bing operations: - service: serp operation_path: /serp/google/organic/live path_template: /serp/{se}/{type}/live method: POST mode: live description: Live organic results discovery_source: static total_services: 1 groups: mixed: - service: serp category: serp discovery_source: mixed title: SERP API description: >- Search engine results across web and vertical engines examples: - google - bing operations: - service: serp operation_path: /serp/google/organic/live path_template: /serp/{se}/{type}/live method: POST mode: live description: Live organic results discovery_source: static supports_custom_paths: true supports_any_dataforseo_path: true 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: true cache_hit: false provider_calls: 0 '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 '404': description: Provider not found 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: notFound: value: error: code: NOT_FOUND message: Provider not found request_id: req_123 details: provider: unknown 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 ````