# Search

Search for relevant data from your clone's digital mind. Supports semantic search, keyword/phrase matching, and optional scoping to specific content sources.

Endpoint: `POST /v3/search/query`

Request body:

| Field        | Type      | Required | Description                                                              |
| ------------ | --------- | -------- | ------------------------------------------------------------------------ |
| `query`      | string\[] | Yes      | Semantic search strings (e.g. questions or topics)                       |
| `keywords`   | string\[] | No       | Keyword or phrase strings for exact-match (BM25) boosting                |
| `content`    | string\[] | No       | Content descriptions to scope results to matching sources                |
| `contentIds` | string\[] | No       | Direct content IDs to filter results to specific sources                 |
| `limit`      | number    | No       | Max chunks to return (1–50, default 10)                                  |
| `tag`        | string    | No       | Access tier tag (e.g. `PUBLIC`, `PREMIUM`). Defaults to broadest access. |

> **How search works:** `query` strings are used for semantic (meaning-based) search. `keywords` are routed through hybrid search for better exact-phrase matching via BM25. When both are provided, results are merged and deduplicated, keeping the highest-scoring passages.

> **Content scoping:** Use `content` to describe the sources you want to search within (e.g. `["Series A fundraising podcast"]`). The API resolves these descriptions to matching content and restricts the chunk search to those sources. Alternatively, pass `contentIds` directly if you already know the content IDs.

Example request:

```bash
curl -X POST https://api.delphi.ai/v3/search/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": ["What is your advice on building a startup?"],
    "keywords": ["fundraising", "Series A"],
    "limit": 5
  }'
```

Example response:

```json
{
  "chunks": [
    {
      "text": "When it comes to fundraising, the most important thing is to have a clear vision and a solid team. Investors want to see that you've thought deeply about the problem...",
      "sources": [
        {
          "contentId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "title": "Startup Fundraising Masterclass"
        }
      ],
      "createdTime": "2025-06-15T10:30:00.000Z",
      "editedTime": "2025-06-15T10:30:00.000Z"
    },
    {
      "text": "For a Series A, you typically need to show strong product-market fit, a growing user base, and a path to revenue...",
      "sources": [
        {
          "contentId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "title": "Startup Fundraising Masterclass"
        }
      ],
      "createdTime": "2025-06-10T08:00:00.000Z",
      "editedTime": "2025-06-10T08:00:00.000Z"
    }
  ],
  "content": [
    {
      "contentId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "title": "Startup Fundraising Masterclass",
      "contentType": "podcast",
      "summary": "A deep dive into fundraising strategies for early-stage startups.",
      "metaData": {},
      "createdTime": "2025-05-01T00:00:00.000Z",
      "editedTime": "2025-05-01T00:00:00.000Z"
    }
  ]
}
```

Response fields:

| Field                          | Type      | Description                                                       |
| ------------------------------ | --------- | ----------------------------------------------------------------- |
| `chunks`                       | object\[] | Matching passages from the knowledge base                         |
| `chunks[].text`                | string    | The passage text                                                  |
| `chunks[].sources`             | object\[] | Content sources this passage belongs to                           |
| `chunks[].sources[].contentId` | string    | Unique ID of the content source                                   |
| `chunks[].sources[].title`     | string    | Title of the content source                                       |
| `chunks[].createdTime`         | string    | When the passage was created                                      |
| `chunks[].editedTime`          | string    | When the passage was last updated                                 |
| `content`                      | object\[] | Deduplicated list of all content sources referenced by the chunks |

> The `content` array includes full metadata for every content source that appears in the chunk results. Use this to display source cards, links, or attribution without making additional API calls.

#### Example: scoped search

Search only within specific content by providing descriptions:

```bash
curl -X POST https://api.delphi.ai/v3/search/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": ["What do you think about AI?"],
    "content": ["podcast episode about artificial intelligence"],
    "limit": 3
  }'
```

Or filter by known content IDs:

```bash
curl -X POST https://api.delphi.ai/v3/search/query \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": ["What do you think about AI?"],
    "contentIds": ["c1a2b3c4-d5e6-7890-abcd-ef1234567890"],
    "limit": 3
  }'
```

### Search content sources

Search for content sources (documents, articles, podcasts, etc.) in the knowledge base by title or description. Use this to discover what content is available before performing a chunk search.

Endpoint: `POST /v3/search/content`

Request body:

| Field   | Type      | Required | Description                                                              |
| ------- | --------- | -------- | ------------------------------------------------------------------------ |
| `query` | string\[] | Yes      | Content search strings (titles, descriptions, topics)                    |
| `tag`   | string    | No       | Access tier tag (e.g. `PUBLIC`, `PREMIUM`). Defaults to broadest access. |

Example request:

```bash
curl -X POST https://api.delphi.ai/v3/search/content \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "query": ["fundraising", "startup advice"]
  }'
```

Example response:

```json
{
  "content": [
    {
      "contentId": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "title": "Startup Fundraising Masterclass",
      "contentType": "podcast",
      "summary": "A deep dive into fundraising strategies for early-stage startups.",
      "metaData": {},
      "createdTime": "2025-05-01T00:00:00.000Z",
      "editedTime": "2025-05-01T00:00:00.000Z"
    },
    {
      "contentId": "d2b3c4d5-e6f7-8901-bcde-f12345678901",
      "title": "My Top 10 Startup Lessons",
      "contentType": "article",
      "summary": "Key lessons learned from building and scaling three companies.",
      "metaData": {},
      "createdTime": "2025-04-15T00:00:00.000Z",
      "editedTime": "2025-04-15T00:00:00.000Z"
    }
  ]
}
```

Content item fields:

| Field         | Type   | Description                                                 |
| ------------- | ------ | ----------------------------------------------------------- |
| `contentId`   | string | Unique identifier for the content source                    |
| `title`       | string | Title of the content                                        |
| `contentType` | string | Type of content (e.g. `podcast`, `article`, `pdf`, `video`) |
| `summary`     | string | Brief summary of the content (may be null)                  |
| `metaData`    | object | Additional metadata (varies by content type)                |
| `createdTime` | string | When the content was added                                  |
| `editedTime`  | string | When the content was last updated                           |

> Use content search to build a content catalog or let users browse available sources before diving into specific passages with `/v3/search/query`.