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

# List Institutions

> List research institutions (optionally name-filtered); use the returned name as the institutions[] search filter value.

## 机构列表

**URL**: `/v1/institutions`
**方法**: `GET`\
**描述**: 获取研究机构列表（可按名称过滤）。返回的 `name` 即为在文档搜索中传入 `institutions[]` 过滤条件的取值。

### 请求参数

| 参数名        | 类型  | 必填 | 描述             |
| ---------- | --- | -- | -------------- |
| query      | str | 否  | 机构名称过滤，不区分大小写。 |
| page\_num  | int | 否  | 页码，默认 `1`。     |
| page\_size | int | 否  | 每页数量，默认 `50`。  |

### 响应参数

| 参数名          | 类型    | 描述                                      |
| ------------ | ----- | --------------------------------------- |
| total\_count | int   | 机构总数。                                   |
| total\_page  | int   | 总页数。                                    |
| page\_num    | int   | 当前页码。                                   |
| page\_size   | int   | 每页数量。                                   |
| institutions | array | 机构列表。                                   |
|   id         | str   | 机构 ID（symbol）。                          |
|   name       | str   | 机构名称，将其作为 `institutions[]` 搜索过滤条件的取值传入。 |

### 请求示例

**cURL**

```bash theme={null}
curl -X GET "https://api.reportify.cn/v1/institutions?query=中金&page_num=1&page_size=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```

**Python**

```python theme={null}
import requests

url = "https://api.reportify.cn/v1/institutions"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
params = {
    "query": "中金",
    "page_num": 1,
    "page_size": 50,
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

### 响应示例

```json theme={null}
{
  "total_count": 1,
  "total_page": 1,
  "page_num": 1,
  "page_size": 50,
  "institutions": [
    {
      "id": "cicc",
      "name": "中国国际金融股份有限公司"
    }
  ]
}
```

<Note>
  将响应中的 `name` 字段值传入文档搜索接口的 `institutions[]` 过滤条件，即可按该机构筛选研报。
</Note>

### 错误响应

| 状态码 | 描述        |
| --- | --------- |
| 422 | 请求参数验证失败。 |


## OpenAPI

````yaml GET /v1/institutions
openapi: 3.1.0
info:
  title: Reportify API
  version: 1.0.0
  description: API documentation for Reportify's document management and search services.
servers:
  - url: https://api.reportify.cn
    description: Production server
security:
  - BearerAuth: []
paths:
  /v1/institutions:
    get:
      tags:
        - openapi-institutions
      summary: List Institutions
      description: >-
        List research institutions (optionally name-filtered); use the returned
        name as the institutions[] search filter value.
      operationId: list_institutions_reportify_api_v1_institutions_get
      parameters:
        - description: Case-insensitive institution name filter
          required: false
          schema:
            type: string
            title: Query
            description: Case-insensitive institution name filter
          name: query
          in: query
        - required: false
          schema:
            type: integer
            title: Page Num
            default: 1
          name: page_num
          in: query
        - required: false
          schema:
            type: integer
            title: Page Size
            default: 50
          name: page_size
          in: query
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAIInstitutionPagination'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    OAIInstitutionPagination:
      properties:
        total_count:
          type: integer
          title: Total Count
          default: 0
        total_page:
          type: integer
          title: Total Page
          default: 0
        page_num:
          type: integer
          title: Page Num
          default: 1
        page_size:
          type: integer
          title: Page Size
          default: 50
        institutions:
          items:
            $ref: '#/components/schemas/OAIInstitutionResponse'
          type: array
          title: Institutions
      type: object
      title: OAIInstitutionPagination
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OAIInstitutionResponse:
      properties:
        id:
          type: string
          title: Id
          description: Institution id (symbol)
        name:
          type: string
          title: Name
          description: Institution name — pass into institutions[] filter
      type: object
      required:
        - id
        - name
      title: OAIInstitutionResponse
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your Bearer token

````