> For the complete documentation index, see [llms.txt](https://docs.sunbirdrc.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sunbirdrc.dev/api-reference/discovery-api/search-an-entity.md).

# Search An Entity

<mark style="color:green;">`POST`</mark> `/api/v1/{entity-name}/search`

#### Path Parameters

| Name                                          | Type   | Description                       |
| --------------------------------------------- | ------ | --------------------------------- |
| entity-name<mark style="color:red;">\*</mark> | String | Name of the entity to be searched |

#### Headers

| Name                                           | Type   | Description               |
| ---------------------------------------------- | ------ | ------------------------- |
| content-type<mark style="color:red;">\*</mark> | String | Set to `application/json` |

#### Request Body

| Name                                  | Type   | Description                                       |
| ------------------------------------- | ------ | ------------------------------------------------- |
| ...<mark style="color:red;">\*</mark> | Object | Filters to be sent in order to identify an entity |

{% tabs %}
{% tab title="200: OK Success Response of Search" %}

```javascript
[
    {
        "school": "UP Public School",
        "name": "Pranav Agate",
        "contact": "1234567890",
        "subject": "Math",
        "osid": "{id}",
        "osOwner": ["{osOwner}"]
    }
]
```

{% endtab %}
{% endtabs %}

Sample Request Body

> {\
> "filters": {\
> "school": {\
> "eq": "UP Public School"\
> }\
> },\
> "limit": 1,\
> "offset": 0\
> }

> Important Fields in Request Body

| Field            | Type   | Description                                                                                                                                                             |
| ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| limit            | Number | Number of responses to be retrieved out of total number of search results                                                                                               |
| offset           | Number | Starting point for responses to be returned                                                                                                                             |
| viewTemplateId   | String | Any operation to be carried on the response before it is returned via API, that can be provided here. For eg: Combining First Name and Last Name into Single Field Name |
| Filter Operators | String | eq, neq, gte, gt, lte, lt, contains, notContains, between, or, startsWith, notStartsWith, endsWith, notEndsWith, queryString are some of the operators provided         |

### Usage

### cURL

```
curl --location \
    --request POST \
    --header 'Content-Type: application/json' \
    '{registry-url}/api/v1/Place/search' \
    --data-raw '{
        "filters": {
            "name": {
                "eq": "UP Public School"
            }
        },
        "limit": 1,
        "offset": 0
    }'
```

### HTTPie

```
printf '{
    "filters": {
        "school": {
            "eq": "UP Public School"
        }
    },
    "limit": 1,
    "offset": 0
}'| http POST '{registry-url}/api/v1/Place/search' \
 Content-Type:'application/json' \
```

> `{registry-url}` is usually [http://localhost:{port}](https://docs.sunbirdrc.dev/api-reference/discovery-api/http:/localhost:{port}). The port can be found under the `registry` section in the `docker-compose.yml` file and is usually `8081`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sunbirdrc.dev/api-reference/discovery-api/search-an-entity.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.