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

# List Services (Authenticated)

> The service catalog as your account sees it, with optional semantic search

## Overview

Returns the catalog as the caller sees it. Without `query`, the full public catalog comes from a background-refreshed snapshot and is returned with an `ETag`; services you hid in your preferences are left out, and paid tiers also get their own private and organization-internal services. With `query`, results come from semantic search (embeddings merged with a keyword pass), cut at `limit`.

[List Services](/api-reference/endpoint/list_services) at `/v1/services/public` is the anonymous catalog: it takes `category`, `sort` and `limit` but not `query`, and never includes a caller's private services.

Responses without `query` carry `ETag` and `Cache-Control: private, no-cache`. Send the `ETag` back in `If-None-Match` to receive `304 Not Modified` when nothing changed.

**Auth:** Optional. API key (`danube-api-key` header) or JWT. Anonymous and free-tier callers get the public catalog only.

## Query Parameters

<ParamField query="service_type" type="string">
  `api`, `mcp_server` or `internal`
</ParamField>

<ParamField query="query" type="string">
  Semantic search over names and descriptions. Search responses are not cached.
</ParamField>

<ParamField query="limit" type="integer" default={20}>
  Maximum results, 1 to 100. Applies only with `query`; without it the whole catalog is returned.
</ParamField>

<ParamField query="include_private" type="boolean" default={true}>
  Include your private and organization-internal services. Honoured for paid tiers only; forced to `false` for anonymous and free-tier callers.
</ParamField>

## Response

Returns an array of service objects. Every field of the service record is present, with `null` where a field does not apply.

<ResponseField name="id" type="string">
  Service UUID
</ResponseField>

<ResponseField name="name" type="string">
  Service name
</ResponseField>

<ResponseField name="slug" type="string">
  Human-readable identifier
</ResponseField>

<ResponseField name="summary" type="string">
  One-line summary
</ResponseField>

<ResponseField name="description" type="string">
  Service description
</ResponseField>

<ResponseField name="service_type" type="string">
  `api`, `mcp_server` or `internal`
</ResponseField>

<ResponseField name="category" type="string">
  One of the 15 marketplace categories
</ResponseField>

<ResponseField name="logo" type="string">
  Logo URL
</ResponseField>

<ResponseField name="contact" type="object">
  Contact block. `contact.url` is the service's website.
</ResponseField>

<ResponseField name="security_schemes" type="object">
  Auth schemes the service declares
</ResponseField>

<ResponseField name="credential_schema" type="object">
  What a caller needs to provide to connect, or `null`. `mcp_auth_config` is always `null` on this route.
</ResponseField>

<ResponseField name="visibility" type="string">
  `public`, `private`, `internal` or `local_only`
</ResponseField>

<ResponseField name="verification_tier" type="string">
  `unverified`, `verified` or `official`
</ResponseField>

<ResponseField name="status" type="string">
  `active`, `degraded` or `retired`
</ResponseField>

<ResponseField name="is_demo" type="boolean">
  A sample-data service, ranked behind real services in search
</ResponseField>

<ResponseField name="tool_count" type="integer">
  Number of tools
</ResponseField>

<ResponseField name="total_executions" type="integer">
  Lifetime calls. `0` for your own private services.
</ResponseField>

<ResponseField name="success_rate" type="number">
  Lifetime success rate. `0` for your own private services.
</ResponseField>

<ResponseField name="avg_rating" type="number">
  Average user rating, or `null`
</ResponseField>

<ResponseField name="rating_count" type="integer">
  Number of user ratings, or `null` when the service has none
</ResponseField>

<ResponseField name="is_popular" type="boolean">
  `total_executions` is at least 100
</ResponseField>

<ResponseField name="is_trending" type="boolean">
  Calls this week exceed 10 and twice last week's
</ResponseField>

The remaining fields, in full: `version`, `license`, `mcp_server_url`, `mcp_transport`, `mcp_auth_type`, `mcp_auth_config`, `mcp_connected`, `mcp_last_connected`, `mcp_connection_type`, `mcp_local_command`, `mcp_local_args`, `mcp_local_env`, `mcp_process_id`, `mcp_health_check_url`, `mcp_requirements_txt`, `mcp_python_version`, `mcp_venv_path`, `mcp_package_name`, `mcp_package_type`, `mcp_package_version`, `official_integration`, `official_provider`, `documentation_url`, `api_base_url`, `owner_id`, `org_id`, `is_verified`, `metadata`, `import_source`, `import_metadata`, `openapi_spec_url`, `created_at`, `updated_at`.

## Example

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.danubeai.com/v1/services?query=email&limit=10" \
    -H "danube-api-key: YOUR_API_KEY"
  ```

  ```python Python SDK theme={null}
  from danube import DanubeClient

  with DanubeClient(api_key="YOUR_API_KEY") as client:
      services = client.services.list(query="email")
      for s in services:
          print(f"{s.name}: {s.tool_count} tools")
  ```

  ```typescript TypeScript SDK theme={null}
  import { DanubeClient } from 'danube';

  const client = new DanubeClient({ apiKey: 'YOUR_API_KEY' });
  const services = await client.services.list({ query: 'email', limit: 10 });
  for (const s of services) {
    console.log(`${s.name}: ${s.toolCount} tools`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  [
    {
      "id": "svc_resend_001",
      "name": "Resend",
      "summary": "Transactional email delivery",
      "description": "Send transactional email, manage domains and audiences.",
      "version": "1.0.0",
      "service_type": "api",
      "contact": {"name": "Resend", "url": "https://resend.com", "email": null},
      "license": {"name": null, "url": null},
      "logo": "https://resend.com/favicon.ico",
      "security_schemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}},
      "mcp_server_url": null,
      "mcp_transport": "http",
      "mcp_auth_type": null,
      "mcp_auth_config": null,
      "mcp_connected": false,
      "mcp_last_connected": null,
      "mcp_connection_type": "remote",
      "mcp_local_command": null,
      "mcp_local_args": null,
      "mcp_local_env": null,
      "mcp_process_id": null,
      "mcp_health_check_url": null,
      "mcp_requirements_txt": null,
      "mcp_python_version": null,
      "mcp_venv_path": null,
      "mcp_package_name": null,
      "mcp_package_type": null,
      "mcp_package_version": null,
      "credential_schema": {
        "fields": [{"name": "api_key", "type": "string", "required": true}]
      },
      "official_integration": false,
      "official_provider": null,
      "documentation_url": "https://resend.com/docs",
      "api_base_url": "https://api.resend.com",
      "visibility": "public",
      "owner_id": null,
      "org_id": null,
      "is_verified": true,
      "is_demo": false,
      "metadata": {},
      "slug": "resend",
      "category": "communication",
      "verification_tier": "verified",
      "status": "active",
      "import_source": "openapi",
      "import_metadata": {},
      "openapi_spec_url": null,
      "created_at": "2026-09-07T18:22:10.000000Z",
      "updated_at": "2026-09-09T11:05:41.000000Z",
      "tool_count": 24,
      "total_executions": 130,
      "success_rate": 0.98,
      "avg_rating": null,
      "rating_count": null,
      "is_trending": false,
      "is_popular": true
    }
  ]
  ```
</ResponseExample>

## MCP Tool

This endpoint is also available as the `list_services` MCP tool:

```python theme={null}
result = await mcp.call_tool("list_services", {
    "query": "email",
    "limit": 10
})
```