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

# Discover

> Search for data endpoints using natural language.

Search for data endpoints using natural language. The API uses AI-powered routing to match your query to the best available endpoints.

## Request

```text theme={null}
POST /v1/discover
```

### Headers

| Header          | Required | Description        |
| --------------- | -------- | ------------------ |
| `Authorization` | Yes      | `Bearer <api-key>` |
| `Content-Type`  | Yes      | `application/json` |

### Body

| Field      | Type   | Required | Description                                                                                                                                                                                                       |
| ---------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`    | string | Yes      | A short natural language search query (1-1000 characters)                                                                                                                                                         |
| `limit`    | number | No       | Maximum results to return (default 5, max 40)                                                                                                                                                                     |
| `minScore` | number | No       | Minimum relevance score. Results scoring below this are filtered out. Scores fall in `(0, 1)`, so useful values are in that range (default 0.2; the schema accepts up to 2, but values above 1 return no results) |

### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.monid.ai/v1/discover \
    -H "Authorization: Bearer monid_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "query": "twitter posts about AI",
      "limit": 5
    }'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch("https://api.monid.ai/v1/discover", {
    method: "POST",
    headers: {
      "Authorization": "Bearer monid_live_...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: "twitter posts about AI",
      limit: 5,
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.monid.ai/v1/discover",
      headers={
          "Authorization": "Bearer monid_live_...",
          "Content-Type": "application/json",
      },
      json={
          "query": "twitter posts about AI",
          "limit": 5,
      },
  )

  data = response.json()
  ```
</CodeGroup>

## Response

### 200 OK

| Field                      | Type                | Description                                                                                                                                              |
| -------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `results`                  | array               | Matching endpoints                                                                                                                                       |
| `results[].provider`       | string              | Provider slug                                                                                                                                            |
| `results[].providerName`   | string \| undefined | Provider display name (may be absent)                                                                                                                    |
| `results[].endpoint`       | string              | Endpoint path                                                                                                                                            |
| `results[].description`    | string              | Endpoint description                                                                                                                                     |
| `results[].score`          | number              | Final relevance score in `(0, 1)`, used for sorting                                                                                                      |
| `results[].tags`           | string\[]           | Endpoint tags                                                                                                                                            |
| `results[].scoreBreakdown` | object              | Per-signal breakdown of the score (`querierScore` plus one entry per signal)                                                                             |
| `results[].price`          | object              | Pricing information                                                                                                                                      |
| `results[].price.type`     | string              | Pricing model, e.g. `"PER_CALL"`, `"PER_RESULT"` (other types such as `"BY_PERIOD"`, `"PER_UNIT_MATRIX"`, `"METERED"` may appear with additional fields) |
| `results[].price.amount`   | object              | Price as `{ "value": number, "currency": "USD" }`                                                                                                        |
| `results[].hints`          | object \| undefined | Ready-to-use next-step commands (may be absent)                                                                                                          |
| `query`                    | string              | The original search query                                                                                                                                |
| `count`                    | number              | Number of results returned                                                                                                                               |

### Example Response

```json theme={null}
{
  "results": [
    {
      "provider": "apify",
      "providerName": "Apify",
      "endpoint": "/apidojo/tweet-scraper",
      "description": "Scrape tweets by search terms, hashtags, or user handles",
      "score": 0.87,
      "tags": ["twitter", "social-media"],
      "scoreBreakdown": { "querierScore": 0.82 },
      "price": {
        "type": "PER_CALL",
        "amount": {
          "value": 0.003,
          "currency": "USD"
        }
      }
    }
  ],
  "query": "twitter posts about AI",
  "count": 1
}
```

## Next Step

Use [`POST /v1/inspect`](/docs/api/inspect) to get full details for a discovered endpoint.