> ## Documentation Index
> Fetch the complete documentation index at: https://help.impactu.colav.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducción

> Conoce la estructura general de la API de ImpactU: URL base, formato de las respuestas, paginación, filtros y errores.

La API de ImpactU es una API REST de solo lectura que devuelve información científica y académica en formato JSON: personas, productos, afiliaciones, fuentes, patentes, proyectos y entidades geográficas.

## URL base

```text theme={null}
https://api.dev.impactu.colav.co
```

Todas las rutas de esta documentación se agregan a esa URL. Por ejemplo, `GET /search/works` se consulta en `https://api.dev.impactu.colav.co/search/works`.

## Formato de las respuestas

Las respuestas son JSON y tienen dos formas, según el tipo de endpoint.

> [tab] Un recurso
>
> Los endpoints que devuelven una sola entidad envuelven el resultado en `data` y agregan `meta`, con la misma forma que en los listados (`count` vale `1`).
>
> ```json theme={null}
> {
>   "data": { "...": "..." },
>   "meta": {
>     "count": 1,
>     "page": 1,
>     "size": 1,
>     "db_response_time_ms": 25,
>     "cursor": { "next": null, "previous": null }
>   }
> }
> ```

> [tab] Un listado
>
> Los endpoints de búsqueda devuelven una lista en `data` y los datos de paginación en `meta`.
>
> ```json theme={null}
> {
>   "data": [ { "...": "..." } ],
>   "meta": {
>     "count": 1542618,
>     "page": 1,
>     "size": 10,
>     "db_response_time_ms": 348,
>     "cursor": { "next": "https://...", "previous": null }
>   }
> }
> ```

Algunos endpoints devuelven el objeto sin envolver en `data`: los filtros disponibles, las afiliaciones relacionadas (de una afiliación o de una entidad geográfica), `/info` y `/info/quality`. Las exportaciones devuelven un archivo CSV o Excel.

### Campo `meta` de los listados

**meta** `object`

Metadatos de la respuesta.

**propiedades**

**count** `integer`

Total de resultados que cumplen la consulta.

**page** `integer`

Página actual.

**size** `integer`

Cantidad de resultados devueltos en esta página.

**db\_response\_time\_ms** `integer`

Tiempo de respuesta de la base de datos en milisegundos.

**cursor** `object`

**propiedades**

**next** `string | null`

URL de la página siguiente.

**previous** `string | null`

URL de la página anterior.

## Convenciones de los listados

Los endpoints de búsqueda comparten estos parámetros de consulta.

**keywords** `string`

Texto de búsqueda. Se usa en las búsquedas desde caja de texto.

**max** `integer` (default: 10)

Resultados por página, de 1 a 250.

**page** `integer` (default: 1)

Número de página.

**sort** `string` (default: citations\_desc)

Ordenamiento con el formato `campo_direccion`, donde la dirección es `asc` o
`desc`. Los campos válidos dependen de la entidad y se describen en cada
endpoint.

**view** `string` (default: full)

Nivel de detalle de la respuesta: `full` (todos los campos) o `summary` (solo
los campos principales). Lo aceptan los listados y los detalles de las
entidades, salvo la búsqueda y el detalle de entidades geográficas y las
noticias.

Además, cada listado tiene sus propios filtros. Todos aceptan varios valores separados por coma (por ejemplo, `years=2020,2026`), y las opciones válidas se consultan en el endpoint de filtros disponibles de cada entidad.

> [!NOTE]
>
> Si no envías `max`, `page` ni `sort`, se aplican `max=10`, `page=1` y
> `sort=citations_desc`. Si envías `max` y `page` sin `sort`, se aplica
> `sort=citations_desc`.

## Datos y formatos

> [accordion] Fechas
>
> Las fechas se expresan en segundos Unix. En las fechas de fin, un valor `-1` indica que la relación sigue vigente.

> [accordion] Identificadores
>
> Cada entidad tiene su propio formato de identificador:
>
> | Entidad | Ejemplo |
> | - | - |
> | Institución | `03bp5hc83` (identificador ROR) |
> | Facultad | `03bp5hc83_20` |
> | Departamento | `03bp5hc83_2_21620003_3154` |
> | Grupo de investigación | `COL0001262` |
> | Persona | `0000000001` |
> | Producto, fuente | `6ab555045418a51e325f5303` |

> [accordion] Información por fuente
>
> Muchos campos (nombres, citas, tipos, rankings) devuelven un elemento por cada fuente de información, con los campos `source` y `provenance`.

## Autenticación y límites

Los endpoints de consulta son públicos: no requieren autenticación y por ahora no tienen límite de solicitudes.

Requieren sesión la administración de usuarios (`/admin/users`), la gestión del API Key (`/users/{email}/apikey`), el estado de sesión (`/me`) y la carga de archivos en `/submit/staff`, `/submit/ciarp` y `/submit/scienti`. La sesión es el JWT que [Iniciar sesión](https://help.impactu.colav.co/api-reference/auth/login.md) guarda en la cookie HttpOnly `access_token_cookie`.

## Errores

Cuando una solicitud falla, la API responde con el código HTTP del caso y un mensaje en `error`:

| Código | Cuándo |
| - | - |
| `400` | Un parámetro es inválido: por ejemplo `max=0`, un `sort` mal formado o un campo de `fields` que no está permitido. |
| `401` | Falta la sesión o el token no es válido. |
| `403` | La sesión no tiene permiso para la operación. |
| `404` | La entidad no existe. |
| `409` | La operación choca con un registro existente, por ejemplo al crear un usuario. |
| `500` | Error inesperado del servidor. |

```json theme={null}
{ "error": "The person with id 9999999999 does not exist." }
```

Los endpoints de autenticación, usuarios y carga de archivos responden con `{ "success": false, "msg": "..." }` en lugar de `error`, salvo [Validar archivo de proyectos](https://help.impactu.colav.co/api-reference/submit/project.md).

Los listados de una entidad que no existe (por ejemplo, los productos de un autor inexistente) responden `200` con la lista vacía.

## Endpoints disponibles

> [card] [Search](https://help.impactu.colav.co/api-reference/search/persons.md)
>
> Búsqueda de personas, productos, afiliaciones, fuentes, patentes, proyectos
> y geografía, con sus endpoints de filtros disponibles.

> [card] [Affiliation](https://help.impactu.colav.co/api-reference/affiliation/get-affiliation.md)
>
> Consulta de una afiliación (institución, facultad, departamento o grupo) por
> su identificador.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.