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

# Buscar registros

> Busca registros por texto, filtros, IDs y ordenamiento.

Busca registros por texto y combina filtros estructurados.

## Endpoint

```text theme={null}
POST /databases/{databaseId}/records/search
```

## Body

| Campo               | Tipo       | Default | Descripción                                                                                 |                      |
| ------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------- | -------------------- |
| `query`             | `string`   | `""`    | Texto libre.                                                                                |                      |
| `filters`           | `array`    | `[]`    | Filtros por campo.                                                                          |                      |
| `page`              | `integer`  | `0`     | Página basada en cero.                                                                      |                      |
| `limit`             | `integer`  | `20`    | Resultados por página.                                                                      |                      |
| `recordIds`         | `string[]` | —       | Restringe la búsqueda a un máximo de `1000` IDs.                                            |                      |
| `include.relations` | `boolean`  | `false` | Incluye vistas resumidas de relaciones y contactos.                                         |                      |
| `sortField`         | `string`   | —       | `key` del campo por el que quieres ordenar.                                                 |                      |
| `sortDirection`     | \`asc      | desc\`  | —                                                                                           | Dirección del orden. |
| `sortType`          | `string`   | —       | Tipo del campo de ordenamiento: `string`, `number`, `boolean`, `date`, `enum` o `relation`. |                      |
| `sortFieldId`       | `string`   | —       | ID del campo de ordenamiento, cuando lo conoces.                                            |                      |

Cada filtro usa esta forma:

```json theme={null}
{
  "fieldId": "<field-id>",
  "operator": "eq",
  "value": "vigente",
  "type": "enum"
}
```

Operadores: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`, `in` y `between`. Tipos opcionales: `string`, `number`, `boolean`, `date`, `enum` y `relation`.

## Ejemplo de solicitud

```bash theme={null}
curl -X POST "https://api.insuranceboosters.com/api/v1/databases/{databaseId}/records/search" \
  -H "Content-Type: application/json" \
  -H "x-ib-api-key: TU_API_KEY" \
  -d '{
    "query": "garcia",
    "page": 0,
    "limit": 20,
    "filters": [
      {
        "fieldId": "<field-id-estado>",
        "operator": "eq",
        "value": "vigente",
        "type": "enum"
      }
    ],
    "include": { "relations": true }
  }'
```

## Respuesta exitosa (`200`)

Devuelve `records`, `total` y `hasMore`. Si solicitas relaciones, también devuelve `included` y `meta`.

<Note>
  Esta operación usa `POST` y recibe los filtros en JSON. No envíes la búsqueda como parámetros de query string.
</Note>

## Errores frecuentes

| HTTP  | Qué significa                        | Qué hacer                                 |
| ----- | ------------------------------------ | ----------------------------------------- |
| `400` | `recordIds` supera `1000` elementos. | Divide la búsqueda en lotes más pequeños. |
| `404` | El tablero no existe.                | Confirma `databaseId`.                    |
| `500` | No fue posible ejecutar la búsqueda. | Reintenta; si continúa, contacta soporte. |


## OpenAPI

````yaml openapi/tableros-v1.yaml POST /databases/{databaseId}/records/search
openapi: 3.1.0
info:
  title: Insurance Boosters API — Tableros
  version: 1.0.0
  description: API pública para administrar tableros, campos, registros y archivos.
  license:
    name: Propietaria
    url: https://insuranceboosters.com
servers:
  - url: https://api.insuranceboosters.com/api/v1
    description: Producción
security:
  - IbApiKey: []
tags:
  - name: Tableros
    description: Administración de tableros.
  - name: Campos
    description: Configuración del esquema de un tablero.
  - name: Registros
    description: Lectura y escritura de registros.
  - name: Archivos
    description: Archivos adjuntos a registros.
paths:
  /databases/{databaseId}/records/search:
    parameters:
      - $ref: '#/components/parameters/DatabaseId'
    post:
      tags:
        - Registros
      summary: Buscar registros
      operationId: searchDatabaseRecords
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRecordsRequest'
            example:
              query: garcia
              filters:
                - fieldId: <field-id-estado>
                  operator: eq
                  value: vigente
                  type: enum
              page: 0
              limit: 20
              include:
                relations: true
      responses:
        '200':
          description: Resultados de la búsqueda.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    DatabaseId:
      name: databaseId
      in: path
      required: true
      description: ID del tablero.
      schema:
        type: string
  schemas:
    SearchRecordsRequest:
      type: object
      additionalProperties: false
      properties:
        query:
          type: string
          default: ''
        filters:
          type: array
          default: []
          items:
            $ref: '#/components/schemas/SearchFilter'
        page:
          type: integer
          minimum: 0
          default: 0
        limit:
          type: integer
          minimum: 1
          default: 20
        recordIds:
          type: array
          maxItems: 1000
          items:
            type: string
        include:
          type: object
          additionalProperties: false
          properties:
            relations:
              type: boolean
              default: false
        sortField:
          type: string
          description: '`key` del campo por el que quieres ordenar.'
        sortDirection:
          type: string
          enum:
            - asc
            - desc
        sortType:
          type: string
          enum:
            - string
            - number
            - boolean
            - date
            - enum
            - relation
          description: Tipo del campo indicado en `sortField`.
        sortFieldId:
          type: string
          description: ID del campo de ordenamiento, cuando lo conoces.
    RecordsResponse:
      type: object
      required:
        - records
        - total
        - hasMore
      properties:
        records:
          type: array
          items:
            $ref: '#/components/schemas/Record'
        total:
          type: integer
        hasMore:
          type: boolean
        included:
          type: object
          additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    SearchFilter:
      type: object
      additionalProperties: false
      required:
        - fieldId
        - operator
        - value
      properties:
        fieldId:
          type: string
        operator:
          type: string
          enum:
            - eq
            - neq
            - gt
            - gte
            - lt
            - lte
            - contains
            - in
            - between
        value:
          description: Valor compatible con el campo y operador.
        type:
          type: string
          enum:
            - string
            - number
            - boolean
            - date
            - enum
            - relation
    Record:
      type: object
      required:
        - id
        - databaseId
        - values
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        databaseId:
          type: string
        values:
          type: object
          additionalProperties: true
        createdAt:
          type: integer
        updatedAt:
          type: integer
        createdBy:
          type: string
        updatedBy:
          type: string
    Error:
      type: object
      properties:
        message:
          type: string
        error:
          type: string
      additionalProperties: false
  responses:
    BadRequest:
      description: Solicitud inválida.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: API key inválida o faltante.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Recurso no encontrado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: Error del servicio.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    IbApiKey:
      type: apiKey
      in: header
      name: x-ib-api-key
      description: API key de Insurance Boosters.

````