# Referencia de la API

La API de Klarety es lo que usan el <Term id="sdk">SDK</Term> de Python y la app. Llámela desde cualquier lenguaje que hable HTTPS y JSON.

<Callout type="info" title="Referencia completa en camino">
Viene una referencia generada con cada campo. Mientras tanto, esta página lista las áreas de endpoints y las páginas del SDK muestran cada llamada en uso.
</Callout>

## URL base [#url-base]

```text
https://api.klarety.ai/v1
```

Todas las solicitudes usan HTTPS con cuerpos JSON.

## Autenticación [#autenticación]

<Steps>
<Step>
### Cambie su clave por un token [#cambie-su-clave-por-un-token]

<Endpoint method="POST" path="/v1/token" />

```bash
curl -s https://api.klarety.ai/v1/token \
  -H "Content-Type: application/json" \
  -d "{\"api_key\": \"$KLARETY_API_KEY\"}"
```

La respuesta trae `access_token`, `token_type` (`Bearer`) y `expires_in` (3600 segundos).
</Step>
<Step>
### Envíelo en cada solicitud [#envíelo-en-cada-solicitud]

```bash
curl -s https://api.klarety.ai/v1/account -H "Authorization: Bearer $TOKEN"
```

Vuelva a cambiar la clave antes de que se cumpla la hora.
</Step>
</Steps>

Vea [Autenticación](/docs/es/developers/authentication) para claves y rotación.

## Convenciones [#convenciones]

### Errores [#errores]

Cada falla es un cuerpo RFC 9457 `application/problem+json` con `type`, `title`, `status`, `detail` e `instance`. Vea [Errores](/docs/es/developers/errors).

### Paginación [#paginación]

Los endpoints de listas devuelven una página y un cursor. Devuélvalo para la página siguiente; un cursor vacío o ausente indica la última página. Su nombre depende del endpoint (`next_cursor` o `next`, devuelto como `cursor` o `after`). El SDK pagina por usted.

### Reintentos seguros [#reintentos-seguros]

- `POST /v1/sql` acepta un `statement_id` (un UUID que usted elige). Reenviarlo nunca ejecuta la sentencia dos veces; devuelve la respuesta, o `"state": "running"` para preguntar de nuevo en `GET /v1/sql/statements/{statement_id}`.
- `POST /v1/tables/{name}/rows/edit` acepta un `write_id`. Una escritura que ya llegó se responde como guardada.

### Tamaños [#tamaños]

Los cuerpos de solicitud tienen un límite de 1 MiB. Los archivos van por enlaces de subida que duran una hora.

## Áreas de endpoints [#áreas-de-endpoints]

### Cuenta y límites [#cuenta-y-límites]

<Endpoint method="GET" path="/v1/account" />
<Endpoint method="GET" path="/v1/whoami" />
<Endpoint method="GET" path="/v1/limits" />
<Endpoint method="GET" path="/v1/usage/storage" />

### SQL y Spark [#sql-y-spark]

<Endpoint method="POST" path="/v1/sql" />
<Endpoint method="GET" path="/v1/sql/statements/{statement_id}" />
<Endpoint method="POST" path="/v1/sql/estimate" />
<Endpoint method="GET" path="/v1/sql/results/{result_id}" />
<Endpoint method="GET" path="/v1/spark/status" />
<Endpoint method="POST" path="/v1/spark/session" />
<Endpoint method="DELETE" path="/v1/spark/session/{session_id}" />

### Tablas y esquemas [#tablas-y-esquemas]

<Endpoint method="GET" path="/v1/schemas" />
<Endpoint method="GET" path="/v1/tables" />
<Endpoint method="POST" path="/v1/tables" />
<Endpoint method="GET" path="/v1/tables/{name}" />
<Endpoint method="GET" path="/v1/tables/{name}/rows" />
<Endpoint method="POST" path="/v1/tables/{name}/rows/edit" />
<Endpoint method="PATCH" path="/v1/tables/{name}/columns" />
<Endpoint method="GET" path="/v1/tables/{name}/snapshots" />
<Endpoint method="POST" path="/v1/tables/{name}/rollback" />

También: reglas, descripciones de columnas, calidad, cambios, autores, borrado definitivo, eliminación y restauración en `/v1/tables/{name}/...`, y restauraciones de copias anteriores en `/v1/restores`.

### Carga y subidas [#carga-y-subidas]

<Endpoint method="POST" path="/v1/ingest/preview" />
<Endpoint method="POST" path="/v1/ingest" />
<Endpoint method="GET" path="/v1/ingest/{run_id}" />
<Endpoint method="POST" path="/v1/uploads" />
<Endpoint method="POST" path="/v1/uploads/complete" />

### Trabajos [#trabajos]

<Endpoint method="POST" path="/v1/batch-jobs" />
<Endpoint method="POST" path="/v1/jobs" />
<Endpoint method="GET" path="/v1/jobs/{job_id}" />
<Endpoint method="DELETE" path="/v1/jobs/{job_id}" />

### Archivos y carpetas [#archivos-y-carpetas]

<Endpoint method="GET" path="/v1/folders" />
<Endpoint method="GET" path="/v1/folders/{folder_id}/entries" />
<Endpoint method="POST" path="/v1/files/uploads" />
<Endpoint method="GET" path="/v1/files" />
<Endpoint method="GET" path="/v1/files/{file_id}/link" />
<Endpoint method="POST" path="/v1/folders/{folder_id}/access/grants" />
<Endpoint method="POST" path="/v1/folders/{folder_id}/watches" />

### Conexiones [#conexiones]

<Endpoint method="GET" path="/v1/connections" />
<Endpoint method="POST" path="/v1/connections" />
<Endpoint method="GET" path="/v1/connections/{connection_id}/grant-policy" />
<Endpoint method="POST" path="/v1/connections/{connection_id}/test" />
<Endpoint method="POST" path="/v1/connections/{connection_id}/read" />

### Grafo de conocimiento y búsqueda [#grafo-de-conocimiento-y-búsqueda]

<Endpoint method="GET" path="/v1/knowledge-graph" />
<Endpoint method="PUT" path="/v1/knowledge-graph" />
<Endpoint method="GET" path="/v1/knowledge-graph/overview" />
<Endpoint method="POST" path="/v1/knowledge-graph/around" />
<Endpoint method="POST" path="/v1/knowledge-graph/paths" />
<Endpoint method="POST" path="/v1/search" />

### Agentes [#agentes]

<Endpoint method="GET" path="/v1/projects/{project_id}/agents" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agents/{name}/drafts" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agents/{name}/runs" />
<Endpoint method="GET" path="/v1/projects/{project_id}/agent-runs/{run_id}" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agent-runs/{run_id}/answers" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agent-runs/{run_id}/stop" />

### Proyectos y despliegues [#proyectos-y-despliegues]

<Endpoint method="GET" path="/v1/projects" />
<Endpoint method="POST" path="/v1/projects" />
<Endpoint method="GET" path="/v1/projects/{project_id}" />
<Endpoint method="POST" path="/v1/projects/{project_id}/deploys" />
<Endpoint method="GET" path="/v1/projects/{project_id}/deploys/{deploy_id}" />
<Endpoint method="GET" path="/v1/projects/{project_id}/logs/lines" />

También: secretos y variables del proyecto, miembros, dominios, puertos compartidos y webhooks en `/v1/projects/{project_id}/...`.

## Próximos pasos [#próximos-pasos]

- [Inicio rápido del SDK](/docs/es/developers) para usar la API desde Python.
- [Errores](/docs/es/developers/errors) para códigos de estado y reintentos.
- [Límites y límites de solicitudes](/docs/es/developers/limits) para lo que permite su plan.