Klarety

Referencia de la API

URL base, autenticación, convenciones y las áreas públicas de endpoints de la API de Klarety.

Para desarrolladores

La API de Klarety es lo que usan el de Python y la app. Llámela desde cualquier lenguaje que hable HTTPS y JSON.

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.

URL base

https://api.klarety.ai/v1

Todas las solicitudes usan HTTPS con cuerpos JSON.

Autenticación

Cambie su clave por un token

POST/v1/token
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).

Envíelo en cada solicitud

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

Vuelva a cambiar la clave antes de que se cumpla la hora.

Vea Autenticación para claves y rotación.

Convenciones

Errores

Cada falla es un cuerpo RFC 9457 application/problem+json con type, title, status, detail e instance. Vea Errores.

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

  • 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

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

Cuenta y límites

GET/v1/account
GET/v1/whoami
GET/v1/limits
GET/v1/usage/storage

SQL y Spark

POST/v1/sql
GET/v1/sql/statements/{statement_id}
POST/v1/sql/estimate
GET/v1/sql/results/{result_id}
GET/v1/spark/status
POST/v1/spark/session
DELETE/v1/spark/session/{session_id}

Tablas y esquemas

GET/v1/schemas
GET/v1/tables
POST/v1/tables
GET/v1/tables/{name}
GET/v1/tables/{name}/rows
POST/v1/tables/{name}/rows/edit
PATCH/v1/tables/{name}/columns
GET/v1/tables/{name}/snapshots
POST/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

POST/v1/ingest/preview
POST/v1/ingest
GET/v1/ingest/{run_id}
POST/v1/uploads
POST/v1/uploads/complete

Trabajos

POST/v1/batch-jobs
POST/v1/jobs
GET/v1/jobs/{job_id}
DELETE/v1/jobs/{job_id}

Archivos y carpetas

GET/v1/folders
GET/v1/folders/{folder_id}/entries
POST/v1/files/uploads
GET/v1/files
GET/v1/files/{file_id}/link
POST/v1/folders/{folder_id}/access/grants
POST/v1/folders/{folder_id}/watches

Conexiones

GET/v1/connections
POST/v1/connections
GET/v1/connections/{connection_id}/grant-policy
POST/v1/connections/{connection_id}/test
POST/v1/connections/{connection_id}/read

Grafo de conocimiento y búsqueda

GET/v1/knowledge-graph
PUT/v1/knowledge-graph
GET/v1/knowledge-graph/overview
POST/v1/knowledge-graph/around
POST/v1/knowledge-graph/paths
POST/v1/search

Agentes

GET/v1/projects/{project_id}/agents
POST/v1/projects/{project_id}/agents/{name}/drafts
POST/v1/projects/{project_id}/agents/{name}/runs
GET/v1/projects/{project_id}/agent-runs/{run_id}
POST/v1/projects/{project_id}/agent-runs/{run_id}/answers
POST/v1/projects/{project_id}/agent-runs/{run_id}/stop

Proyectos y despliegues

GET/v1/projects
POST/v1/projects
GET/v1/projects/{project_id}
POST/v1/projects/{project_id}/deploys
GET/v1/projects/{project_id}/deploys/{deploy_id}
GET/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

En esta página

URL baseAutenticaciónCambie su clave por un tokenEnvíelo en cada solicitudConvencionesErroresPaginaciónReintentos segurosTamañosÁreas de endpointsCuenta y límitesSQL y SparkTablas y esquemasCarga y subidasTrabajosArchivos y carpetasConexionesGrafo de conocimiento y búsquedaAgentesProyectos y desplieguesPróximos pasos