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

# Discovery API

> Unified discovery endpoint for PraisonAI servers

# Discovery API

The discovery endpoint provides a unified way to discover all available providers and endpoints on any PraisonAI server.

## Overview

Every PraisonAI server exposes `/__praisonai__/discovery` which returns a JSON document describing:

* Server name and version
* Available providers (agents-api, recipe, mcp, a2a, a2u)
* Available endpoints with their capabilities

## When to Use

* **Client discovery**: Automatically discover server capabilities
* **Health monitoring**: Verify server is running with expected providers
* **Integration**: Build clients that adapt to available endpoints

## Base URL + Playground

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start server
praisonai serve unified --host 127.0.0.1 --port 8765
```

**Base URL:** `http://127.0.0.1:8765`

## Request

<ParamField path="none" type="none">
  No parameters required.
</ParamField>

### Example Request

<CodeGroup>
  ```bash curl theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl http://127.0.0.1:8765/__praisonai__/discovery
  ```

  ```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import requests

  response = requests.get("http://127.0.0.1:8765/__praisonai__/discovery")
  discovery = response.json()
  print(discovery)
  ```

  ```javascript JavaScript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  const response = await fetch("http://127.0.0.1:8765/__praisonai__/discovery");
  const discovery = await response.json();
  console.log(discovery);
  ```
</CodeGroup>

## Response

<ResponseField name="schema_version" type="string" required>
  Discovery schema version (e.g., "1.0.0")
</ResponseField>

<ResponseField name="server_name" type="string" required>
  Server name (e.g., "praisonai-unified")
</ResponseField>

<ResponseField name="server_version" type="string">
  Server version
</ResponseField>

<ResponseField name="providers" type="array" required>
  List of available providers

  <Expandable title="Provider object">
    <ResponseField name="type" type="string" required>
      Provider type: `agents-api`, `recipe`, `mcp`, `tools-mcp`, `a2a`, `a2u`
    </ResponseField>

    <ResponseField name="name" type="string" required>
      Human-readable provider name
    </ResponseField>

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

    <ResponseField name="capabilities" type="array">
      List of capabilities (e.g., `["invoke", "health"]`)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="endpoints" type="array">
  List of available endpoints

  <Expandable title="Endpoint object">
    <ResponseField name="name" type="string" required>
      Endpoint name
    </ResponseField>

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

    <ResponseField name="provider_type" type="string" required>
      Provider type this endpoint belongs to
    </ResponseField>

    <ResponseField name="streaming" type="array">
      Streaming modes: `["none"]`, `["sse"]`, `["websocket"]`
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "schema_version": "1.0.0",
  "server_name": "praisonai-unified",
  "server_version": "1.0.0",
  "providers": [
    {
      "type": "agents-api",
      "name": "Agents API",
      "description": "Agent HTTP API endpoints",
      "capabilities": ["invoke", "health"]
    },
    {
      "type": "recipe",
      "name": "Recipe Runner",
      "capabilities": ["list", "describe", "invoke", "stream"]
    },
    {
      "type": "mcp",
      "name": "MCP Server",
      "capabilities": ["list-tools", "call-tool"]
    },
    {
      "type": "a2a",
      "name": "A2A Protocol",
      "capabilities": ["agent-card", "message-send"]
    },
    {
      "type": "a2u",
      "name": "A2U Event Stream",
      "capabilities": ["subscribe", "stream"]
    }
  ],
  "endpoints": [
    {
      "name": "agents",
      "description": "Agents workflow endpoint",
      "provider_type": "agents-api"
    },
    {
      "name": "events",
      "description": "Agent event stream",
      "provider_type": "a2u",
      "streaming": ["sse"]
    }
  ]
}
```

## Errors

| Status | Description  |
| ------ | ------------ |
| 200    | Success      |
| 500    | Server error |

## CLI Equivalent

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List endpoints from a server
praisonai endpoints list --url http://127.0.0.1:8765

# Get discovery document
praisonai endpoints discovery --url http://127.0.0.1:8765

# Filter by provider type
praisonai endpoints list --url http://127.0.0.1:8765 --type agents-api
```

## Configuration

The discovery document is automatically generated based on the server type:

| Server Type | Providers Included |
| ----------- | ------------------ |
| `unified`   | All providers      |
| `agents`    | agents-api         |
| `recipe`    | recipe             |
| `mcp`       | mcp                |
| `tools`     | tools-mcp          |
| `a2a`       | a2a                |
| `a2u`       | a2u                |

## Notes

* Discovery is always available at `/__praisonai__/discovery`
* No authentication required for discovery endpoint
* Use discovery to build adaptive clients
* Schema version follows semver

## Related

* [Health API](/docs/deploy/api/health-api) - Health check endpoint
* [Endpoints CLI](/docs/cli/endpoints) - CLI for endpoint discovery