API de Kanera

La API pública de Kanera le permite crear integraciones en torno al mismo trabajo que su equipo administra en la aplicación: espacios de trabajo, tableros, tarjetas, listas, separadores de tableros, comentarios, listas de verificación, notas, archivos adjuntos, etiquetas, campos personalizados, tareas, colas de clasificación, actividad y enlaces externos.

Utilice la API cuando Kanera necesite conectarse a otro sistema, impulsar un flujo de trabajo interno, migrar datos, crear informes o permitir que otra herramienta cree y actualice el trabajo de Kanera.

que puedes construir

Los casos de uso comunes de API incluyen:

Sincroniza las tarjetas Kanera con otro rastreador de trabajo.
Cree tarjetas a partir de formularios, tickets de soporte, mensajes de chat o registros de CRM.
Cree paneles de informes personalizados a partir de tableros, tareas, etiquetas, campos personalizados y actividades.
Importe trabajo a Kanera desde otro sistema.
Mantenga registros externos vinculados a tarjetas o notas de Kanera.
Agregue comentarios o actualizaciones de estado desde otra herramienta.
Cargue y adjunte archivos a tarjetas o notas.
Lea el historial de actividad para auditorías, informes o automatización.

Las integraciones de Kanera pueden apuntar a tableros o espacios de trabajo independientes. Un tablero independiente tiene sus propias listas, etiquetas y campos personalizados. Un espacio de trabajo comparte esos recursos entre sus tableros, lo que hace que los flujos de trabajo de sincronización e informes entre tableros sean más fáciles de mantener consistentes.

Clientes oficiales

No tienes que empezar desde curl. Dos clientes propios empaquetan la misma API:

Cliente	Instalar	Úselo para
Kanera CLI	`npm install --global @kanera/cli`	Uso de terminal, scripts de shell y agentes de inteligencia artificial que pueden ejecutar comandos.
SDK de mecanografiado	`npm install @kanera/sdk`	Integraciones de TypeScript y JavaScript. Sin dependencias de tiempo de ejecución; se ejecuta en Node, Bun, Deno, trabajadores y navegadores.

El SDK tiene licencia del MIT, por lo que incorporarlo en su propia aplicación no plantea dudas sobre la política de licencia. Utilice los puntos finales REST directamente para cualquier otro idioma.

Referencia API

La API REST de Kanera está en:

https://api.kanera.app

La referencia detallada a nivel de punto final está disponible en:

https://api.kanera.app/docs

El servicio API público incluye la referencia a nivel de punto final:

Camino	uso
`/docs`	Referencia de API escalar interactiva.
`/swagger`	Referencia de la interfaz de usuario de Swagger.
`/openapi.json`	Documento OpenAPI para generación y herramientas de SDK.

Para Kanera, abra:

https://api.kanera.app/docs
https://api.kanera.app/swagger
https://api.kanera.app/openapi.json

Utilice esta página como guía de introducción y luego utilice la referencia de API para conocer las rutas exactas de los puntos finales, los cuerpos de las solicitudes, los esquemas de respuesta y los tipos de eventos de webhook disponibles.

Utilice la referencia del punto final

Abierto escalar para la referencia del criterio de valoración principal. Cada operación muestra su método y ruta, alcance requerido, ruta y parámetros de consulta, esquema de solicitud, esquema de respuesta y respuestas de error. Usar Autorizar para proporcionar un token de portador cuando desee intentar una solicitud.

uso Interfaz de usuario arrogante cuando sus herramientas o flujo de trabajo se basan en Swagger. Descargar JSON de API abierta para la generación de SDK, validación de solicitudes o importación de la API a otro cliente.

El documento OpenAPI es la fuente de la verdad. Copie un ejemplo de la referencia en lugar de adivinar el cuerpo de una solicitud y pruebe las operaciones de escritura o eliminación en el espacio de trabajo previsto antes de automatizarlas.

Grupos de puntos finales

grupo	Operaciones típicas
Espacios de trabajo y tableros	Descubra trabajos accesibles, abra el estado completo del tablero, administre miembros e invitados y cree o reordene tableros.
Listas, separadores y tarjetas.	Cree, actualice, coloque, mueva, complete, archive, duplique y edite trabajos en masa.
Notas y archivos adjuntos	Cree notas anidadas, administre bloqueos y vínculos de retroceso, cargue archivos directamente o mediante un vínculo de carga único y lea los bytes de un archivo adjunto.
Bloc de notas	Lea las páginas privadas de Scratchpad de la persona que llama y capture tareas rápidas en una página de Bandeja de entrada. Sólo credenciales personales.
Campos y etiquetas	Administre campos personalizados, opciones y etiquetas de tarjetas reutilizables a nivel del espacio de trabajo.
Comentarios y actividad	Lea las transmisiones de tarjetas, escriba comentarios y reacciones y revise la actividad del tablero.
Hasta las próximas prioridades	Descubra colas legibles, enumere el orden de los equipos y agregue, mueva o elimine tarjetas clasificadas.
Siguiendo	Mire o deje de mirar tarjetas y tableros, configure, borre o enumere los recordatorios de sus tarjetas privadas y sondee su bandeja de entrada de notificaciones. Sólo credenciales personales.
El agente se ejecuta	Anuncie que un agente está trabajando en una tarjeta, lata mientras se ejecuta y registre cómo terminó.
Búsqueda y enlaces externos	Busque contenido accesible y mantenga asignaciones idempotentes a registros en otros sistemas.
Ganchos web	Registre y administre puntos finales, inspeccione o reintente entregas y reciba eventos de cambios firmados sin sondeo.

Elija un tipo de clave API

Kanera tiene dos tipos de claves API. Se autentican de la misma manera, pero su modelo de acceso es diferente.

Tipo de clave	Créelo desde	Úselo cuando	Modelo de acceso
Clave API personal	Configuración de perfil -> Claves API	Está conectando su propio script, CLI o cliente MCP y desea que funcione en todos los ámbitos a los que puede acceder personalmente.	Actúa como usted, en todos los espacios de trabajo y tableros a los que puede acceder, respetando su rol en cada tablero. su leer o escribir el alcance limita lo que puede hacer dentro de ese acceso. No puede realizar acciones de administración del espacio de trabajo.
Clave API del espacio de trabajo o del tablero	Configuración del espacio de trabajo -> API o Configuración del tablero -> API	Está configurando una integración de equipo, una cuenta de servicio, un productor de webhooks, un trabajo de sincronización o una automatización para un espacio de trabajo o un tablero independiente.	Con alcance para ese espacio de trabajo o tablero independiente. su leer, escribir, o Administrador El alcance controla lo que la integración puede hacer.

Utilice una clave personal para flujos de trabajo propiedad del usuario. Utilice un espacio de trabajo con alcance o una clave de tablero para integraciones compartidas o de producción que deben ser propiedad del destino, rotarse y auditarse.

Requisitos del plan

Las claves API personales y las conexiones interactivas de agentes de IA funcionan cada plan, incluido el alojamiento gratuito. Actúan como un usuario presente, por lo que llegan exactamente a los tableros que el usuario puede abrir, tanto en organizaciones gratuitas como profesionales.

Se necesitan claves API de tablero y espacio de trabajo, agentes de servicio OAuth desatendidos, webhooks y destinos de chat. Pro o los 30 días prueba profesional. Se ejecutan en nombre de la organización sin que nadie haya iniciado sesión, por lo que no están disponibles en el alojamiento gratuito, donde la página de configuración del espacio de trabajo explica esto en lugar de mostrar el formulario de creación. Solicitudes bloqueadas por devolución de límite de plan 403 con el código de error PLAN_LIMIT, por lo que una integración puede diferenciar un problema de plan de un problema de permiso.

Necesidades de creación de claves API de tablero o espacio de trabajo, clientes OAuth y destinos de chat administrador del espacio de trabajo permiso. Los administradores también administran todos los puntos finales de webhook en un espacio de trabajo; una credencial API con capacidad de escritura o un agente OAuth interactivo puede registrar puntos finales con alcance en su propia conexión cuando su usuario es miembro del espacio de trabajo. Las claves de API personales no necesitan ninguna función de espacio de trabajo para crearse.

La puerta no está sólo a la creación. Cuando una organización alojada pasa a ser gratuita, Kanera revoca sus claves API de tablero y espacio de trabajo activo, lo que también deshabilita los agentes de servicio OAuth creados en ellas, y /api/v1 los rechaza en el momento de la solicitud, por lo que una clave que sobrevive en otro lugar aún no se puede utilizar. Las claves API personales y las conexiones interactivas de agentes siguen funcionando. Los puntos finales de webhook y los destinos de chat se pausan durante la misma degradación. La actualización de nuevo a Pro restaura las claves y los puntos finales afectados por la degradación.

Límites de tarifas

Las solicitudes de claves API y agentes de IA, tanto a través de REST como de MCP, están limitadas por usuario, según los límites del plan de la organización propietaria del tablero al que se accede:

organización de el tablero	Por segundo	Por minuto
Alojado gratis	5	60
Prueba alojada Pro o Pro	20	400
Autohospedado	20	400 (configurable)

Un usuario que pertenece tanto a una organización Gratuita como a una Pro obtiene los límites de cada organización en sus propios tableros. Las solicitudes que superan el límite no se rechazan inmediatamente: hasta 10 esperan en cola, durante un máximo de 10 segundos, y se atienden como capacidad libre. Solo se reciben las solicitudes más allá de esa cola. 429 con un Retry-After encabezado. El servidor CLI, SDK y MCP retroceden y vuelven a intentarlo automáticamente.

Los operadores autohospedados pueden cambiar los límites con PUBLIC_API_KEY_RATE_LIMIT_PER_SECOND, PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE, PUBLIC_API_RATE_LIMIT_QUEUE_SIZE, y PUBLIC_API_RATE_LIMIT_QUEUE_MAX_WAIT_MS. Ver Ganchos web para el comportamiento de degradación total.

Crear una clave API personal

Abierto Configuración de perfil.
Ir a Claves API pestaña.
Cree una clave API personal.
Elige Sólo lectura o leer y escribir.
Agregue una etiqueta privada opcional para que pueda reconocer dónde se usa la clave.
Copie el secreto cuando se muestre.

Las claves personales siempre están vinculadas al usuario que las creó. Siguen el acceso y la función real del propietario en el tablero, y la actividad aparece como el propietario. No hay ámbito de administración: una clave personal nunca puede realizar la administración del espacio de trabajo, cualquiera que sea la función de su propietario.

Claves personales de solo lectura

Una clave personal es leer y escribir a menos que elija lo contrario, que es lo que le proporciona una clave existente o un flujo de creación sin cambios.

Elige Sólo lectura cuando la credencial va a algún lugar que no estarás mirando: un agente de IA, un trabajo de informes, una verificación de CI, un tablero. Una clave de solo lectura puede enumerar, leer, buscar e informar, y Kanera rechaza cada mutación con 403 y el codigo de error FORBIDDEN. Debido a que el rechazo ocurre en la API y no en el cliente, un agente que se porta mal o que se inyecta rápidamente aún no puede cambiar su trabajo.

El alcance se fija cuando se crea la clave. Para cambiarla, cree una nueva clave y revoque la anterior.

El secreto se muestra una vez. Guárdelo en su administrador secreto local, configuración del cliente MCP o variables de entorno.

Crear una clave API de tablero o espacio de trabajo

Abra el espacio de trabajo o el tablero independiente.
Ir a Configuración del espacio de trabajo -> API o Configuración del tablero -> API.
Cree una clave API de espacio de trabajo.
Elija el alcance más pequeño que se ajuste a la integración.
Copie el secreto cuando se muestre.

Las claves de la API del espacio de trabajo están limitadas al espacio de trabajo. Una clave solo puede acceder a los recursos en el espacio de trabajo donde se creó y donde su creador todavía tiene acceso.

El secreto se muestra una vez. Guárdelo en el administrador secreto de su integración o en las variables de entorno.

Ámbitos clave de la API del espacio de trabajo

Alcance	Úselo cuando
leer	La integración solo necesita leer, buscar, informar o exportar datos de Kanera.
escribir	La integración necesita crear o actualizar trabajo, como tarjetas, comentarios, etiquetas, asignados, valores de campos personalizados, notas o archivos adjuntos.
Administrador	La integración necesita operaciones de API públicas a nivel de administrador cuando sean compatibles. Utilice esto con moderación.

leer, escribir, y Administrador se aplican a las teclas del espacio de trabajo y del tablero. Las claves personales eligen entre leer y escribir únicamente, y siempre heredará los permisos a nivel de tablero del propietario además de eso.

Utilice claves API independientes para integraciones independientes. Esto hace que el acceso sea más fácil de revocar, rotar y auditar. Para sistemas compartidos, prefiera las claves del espacio de trabajo para que el acceso no esté vinculado a las herramientas personales de una persona.

Autenticación

Envíe la clave API como token al portador:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer kanera_live_..."

Las claves API de Kanera utilizan prefijos para el entorno:

Prefijo	Medio ambiente
`kanera_live_...`	Producción
`kanera_stg_...`	Puesta en escena
`kanera_dev_...`	Desarrollo
`kanera_test_...`	prueba

Las llaves personales llevan un u marcador después del prefijo del proveedor, por lo que kanera_u_live_... es una clave personal y kanera_live_... Es una llave de espacio de trabajo o tablero. Ambos se autentican de la misma manera.

Devolución de claves faltantes o no válidas 401. Claves válidas sin permiso para la devolución de un recurso u operación 403 - incluido un intento de escritura con una clave de ámbito de lectura.

OAuth para agentes de IA

Kanera admite OAuth 2.0, por lo que un agente de IA compatible puede conectarse a Kanera MCP mediante el consentimiento del navegador o una conexión de servicio en lugar de almacenar una clave API.

Una conexión OAuth es para MCP; No es una credencial API pública en general. Utilice una clave API personal, de espacio de trabajo o de tablero cuando su propia integración necesite llamar /api/v1 directamente.

Hay tres rutas de OAuth:

Agentes interactivos utilice el flujo de código de autorización con PKCE. Una persona aprueba la conexión una vez en el navegador y el agente actúa como ese usuario. Así es como se conectan los clientes MCP compatibles, como Claude, ChatGPT, Copilot y Codex, sin una clave API.
Clientes de dispositivos utilizar la concesión de autorización del dispositivo (urn:ietf:params:oauth:grant-type:device_code). El cliente muestra un código corto, una persona lo aprueba en un navegador en cualquier dispositivo y el cliente busca tokens. Utilícelo para una CLI o un cliente sin cabeza que no pueda recibir una redirección del navegador. Ver el referencia de autorización del dispositivo.
Agentes desatendidos utilizar el client_credentials subvención. Creas una identificación de cliente y un secreto en Configuración del espacio de trabajo -> API y cambiarlos por tokens de corta duración, sin necesidad de navegar por el navegador. Úselos para agentes CI, cron o del lado del servidor.

Ver Conecte un agente de IA para configuración, alcances y administración de conexiones. Los autores de clientes OAuth personalizados pueden encontrar los detalles del protocolo en la Referencia técnica del MCP.

URL base y versiones

Los puntos finales REST se encuentran bajo /api/v1 en el servicio API público.

Por ejemplo:

https://api.kanera.app/api/v1/workspaces

Rutas de ayuda operativa como /docs, /swagger, /openapi.json, las URL de medios firmadas y el descubrimiento de eventos de webhook pueden estar fuera del /api/v1 prefijo. Trate las URL de medios firmadas devueltas por la API como URL opacas y utilícelas según lo previsto.

Primeras solicitudes

Compruebe quién actúa como la credencial. GET /api/v1/session devuelve el usuario, la organización, el tipo de credencial y scope (read significa que cada cambio es rechazado), más el del usuario timeZone y today, la fecha actual en esa zona, por lo que un cliente puede resolver "hoy" o "mañana" de la misma manera que Kanera marca las fechas de vencimiento:

curl "$KANERA_PUBLIC_API_URL/api/v1/session" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Enumere los espacios de trabajo a los que puede acceder la clave API:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Luego, enumere los tableros en un espacio de trabajo:

curl "$KANERA_PUBLIC_API_URL/api/v1/workspaces/$WORKSPACE_ID/boards" \
  -H "Authorization: Bearer $KANERA_API_KEY"

Abra un tablero para obtener el tablero, las listas de espacios de trabajo, los separadores del tablero, las tarjetas visibles, los miembros, las etiquetas y los campos personalizados necesarios para representar o sincronizar el trabajo:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/open" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY"

Crea una tarjeta:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/cards" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Follow up with Acme"}'

Una creación también puede establecer labelIds, assigneeIds, dueDateLocalDate (YYYY-MM-DD), y dueDateSlot en la misma escritura, para que la tarjeta llegue completamente descrita y sus automatizaciones de etiquetas se ejecuten una vez.

Cree varias tarjetas a la vez, hasta 50 por solicitud en un tablero. Cada tarjeta nombra su propia lista y aparece al final de ella en el orden de solicitud:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/cards/bulk/create" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "{\"cards\":[{\"listId\":\"$LIST_ID\",\"title\":\"Draft the brief\",\"labelIds\":[\"$LABEL_ID\"]},{\"listId\":\"$LIST_ID\",\"title\":\"Review with legal\",\"assigneeIds\":[\"$USER_ID\"],\"dueDateLocalDate\":\"2026-11-02\"}]}"

Cada tarjeta se verifica antes de crearla, por lo que una lista, etiqueta o asignado desconocido rechaza toda la solicitud con un 400 que nombra la entrada, como cards[1]: one or more label ids are invalid. Luego, cada tarjeta activa las mismas automatizaciones, notificaciones y webhooks que una sola creación.

Las respuestas de las cartas incluyen lo inmutable. workspaceId, opaco organisationKey, positivo number, legible por humanos actual key como por ejemplo PROJ-123y navegador limpio url. El prefijo del espacio de trabajo puede cambiar, pero el número de tarjeta no.

Resuelva una clave de tarjeta actual o histórica antes de llamar a un punto final de mutación basado en identificación:

curl "$KANERA_PUBLIC_API_URL/api/v1/organisations/$ORGANISATION_KEY/cards/by-key/$CARD_KEY" \
  -H "Authorization: Bearer $KANERA_API_KEY"

La resolución no distingue entre mayúsculas y minúsculas y devuelve la identificación actual, el espacio de trabajo, el tablero, la lista, el número, la clave y la URL del navegador de la tarjeta. La clave de la organización es el valor opaco devuelto por Kanera, no el nombre de la organización ni el slug. Devuelven las tarjetas perdidas e inaccesibles 404.

Actualizar una tarjeta:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Imported from CRM"}'

Añade un comentario:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/comments" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Customer confirmed the rollout window."}'

Reemplace las etiquetas o asignatarios de la tarjeta con un conjunto exacto:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/labels" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"labelIds\":[\"$LABEL_ID\"]}"

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/assignees" \
  -X PUT \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"userIds\":[\"$USER_ID\"]}"

estos dos PUT Las operaciones reemplazan todo el conjunto. Envíe una matriz vacía para borrarla; utilice las operaciones documentadas de agregar/eliminar en masa cuando necesite parchear la semántica en las tarjetas seleccionadas.

Completa una tarjeta:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/completion" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"completed":true}'

Administrar separadores de tablero

Un separador es un elemento de propiedad de el tablero, con título y opcionalmente coloreado en el carril de orden mixto de tarjetas y separadores de una lista de flujo de trabajo. Cree uno en un ancla escrita exactamente:

curl "$KANERA_PUBLIC_API_URL/api/v1/boards/$BOARD_ID/lists/$LIST_ID/separators" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"This week\",\"color\":\"blue\",\"beforeItem\":{\"type\":\"card\",\"id\":\"$CARD_ID\"}}"

Actualiza su título o color con PATCH /api/v1/separators/{id}, muévelo con POST /api/v1/separators/{id}/movey eliminarlo con DELETE /api/v1/separators/{id}. Mover cuerpos nombra el destino listId y suministrar exactamente uno beforeItem o afterItem; el artículo puede ser un { "type": "card", "id": "..." } o { "type": "separator", "id": "..." } referencia. un null afterItem significa la parte superior y una null beforeItem significa el fondo. Al eliminar un separador, las tarjetas no cambian.

Administrar Hasta el siguiente pedido

La API expone las mismas colas clasificadas utilizadas por Inicio, Mis tarjetas y Tarjetas de equipo:

Punto final	uso
`GET /api/v1/work/priority-targets`	Enumere los usuarios cuyas colas puede leer la credencial.
`GET /api/v1/work/priorities`	Lea todas las colas permitidas en una sola respuesta.
`GET /api/v1/work/priorities/{userId}`	Lea una cola en orden de clasificación.
`POST /api/v1/work/priorities/{userId}/cards`	Agregue una tarjeta activa asignada en una posición anclada.
`POST /api/v1/card-priorities/{id}/move`	Mueva una entrada de la cola antes o después de otra entrada visible.
`DELETE /api/v1/card-priorities/{id}`	Retire la entrada sin cambiar la tarjeta.

Las credenciales personales siempre pueden leer su propia cola. Leer la cola de otra persona requiere autoridad administrativa efectiva en un espacio de trabajo compartido, y las escrituras también requieren una credencial con capacidad de escritura más autoridad para la tarjeta de destino. Utilice los identificadores de entrada devueltos por la cola como anclajes de movimiento; Los rangos son valores de presentación, no identificadores de mutación.

Adjuntar y leer archivos

POST /api/v1/cards/{id}/attachments realiza una carga de varias partes. Cuando el archivo se encuentra en algún lugar desde el que la persona que llama no puede transmitirlo directamente, como la zona de pruebas de un agente de IA, cree un enlace de carga único en su lugar y PUT los bytes sin procesar:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/MKT-42/attachments/upload-links" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"test-run.log"}'

# The response includes uploadUrl; no Authorization header is needed for the upload itself.
curl -fsS -T ./test-run.log "$UPLOAD_URL"

El enlace funciona una vez, caduca después de 15 minutos y deja de funcionar si se revoca la clave que lo creó.
Kanera almacena el archivo con el nombre y tipo registrado cuando se creó el enlace, infiriendo el tipo de la extensión cuando se omite mimeType. Archivos de registro (.log, .out, .jsonl, y similares) se almacenan como texto sin formato.
Para crear un enlace se necesita una credencial con capacidad de escritura y acceso de editor a la tarjeta. Los límites de almacenamiento se verifican tanto cuando se crea el enlace como cuando llega el archivo.
La respuesta de carga es el nuevo archivo adjunto, y cualquiera que mire la tarjeta verá que aparece inmediatamente.

Leer los bytes de un archivo adjunto con GET /api/v1/cards/{id}/attachments/{attachmentId}/content. Es compatible Range solicitudes, y ?variant=cover (hasta 1200 px) o ?variant=thumbnail (400px) devuelve las copias JPEG que Kanera hace de imágenes PNG, JPEG, GIF y WebP.

Capturar al bloc de notas

POST /api/v1/scratchpad/capture agrega una tarea abierta al privado de la persona que llama Bloc de notas, en la primera página titulada pageTitle (predeterminado Inbox), y crea la página cuando falta:

curl "$KANERA_PUBLIC_API_URL/api/v1/scratchpad/capture" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Renew the venue insurance"}'

GET /api/v1/scratchpad/notes enumera cada página con su contenido, y PATCH /api/v1/scratchpad/notes/{id} reemplaza una página. Pasa el updatedAt lees como baseUpdatedAt recibir 409 SCRATCHPAD_STALE en lugar de sobrescribir las ediciones realizadas desde entonces. El Scratchpad pertenece a una persona, por lo que las claves API del espacio de trabajo reciben 403; utilice una clave personal o una conexión OAuth.

Ver tarjetas y configurar recordatorios

el Siguiendo Los puntos finales administran las suscripciones de la persona que llama, por lo que las claves API del espacio de trabajo reciben 403; utilice una clave personal o una conexión OAuth. Para cambiarlos se necesita una credencial con capacidad de escritura, pero solo acceso de lectura a la tarjeta.

Punto final	uso
`GET /api/v1/cards/{id}/follow`	Ya sea que mires la tarjeta y tu recordatorio en ella.
`PUT` / `DELETE /api/v1/cards/{id}/watch`	Mira o deja de mirar una tarjeta. Devuelve el mismo estado que `follow`.
`PUT` / `DELETE /api/v1/boards/{id}/watch`	Mira o deja de mirar un tablero.
`PUT /api/v1/cards/{id}/reminder`	Configura tu recordatorio: `{"remindAt": "2026-10-16T15:00:00+01:00"}`.
`DELETE /api/v1/cards/{id}/reminder`	Borra tu recordatorio.
`GET /api/v1/reminders`	Tus recordatorios pendientes, lo más pronto posible primero. `?status=all` incluye los que ya dispararon.
`GET /api/v1/notifications`	Encuesta tu bandeja de entrada de notificaciones desde un cursor. Vea abajo.

remindAt es un instante ISO con un desplazamiento, en el futuro y como máximo 56 días (ocho semanas) por delante. Tiene un recordatorio por tarjeta, por lo que configurarlo nuevamente lo reemplaza y lo rearma. Tus otras sesiones abiertas se actualizan inmediatamente. Ni la visualización ni los recordatorios aparecen en la actividad de la tarjeta. Ver Recordatorios.

GET /api/v1/notifications es para un script o agente que no puede recibir webhooks, como uno que se ejecuta en una computadora portátil. Devuelve las mismas filas que su cajón de notificaciones (respuestas, menciones, asignaciones y cambios en las tarjetas que mira o están asignadas), las más antiguas primero. Llámalo una vez sin since para las últimas filas, luego pase el valor de cada respuesta cursor volver como since, repitiendo mientras hasMore es true, para conseguir sólo lo nuevo. Cada fila lleva una línea summary, el card clave y URL, el actor, y un commentExcerpt para comentarios. Las filas aparecen unos segundos después del evento. Una conexión de agente de IA no ve las notificaciones causadas por sus propias escrituras a menos que agregue includeSelf=truey las encuestas nunca marcan nada leído.

Seguimiento del trabajo en vuelo de un agente

Cuando la persona que llama es un agente de IA en lugar de un trabajo de sincronización, puede anunciar el trabajo que está realizando en una tarjeta. Luego, Kanera muestra un chip activo en el mosaico de la tarjeta, enumera la ejecución detallada de la tarjeta y registra las filas de actividad de la tarjeta para el inicio y el final, de modo que una persona pueda ver que algo está sucediendo y quién lo está haciendo, sin esperar el resultado.

Punto final	uso
`POST /api/v1/cards/{cardId}/agent-runs`	Comienza una carrera. el cuerpo toma `title` (obligatorio), `summary`, y `externalUrl`.
`GET /api/v1/cards/{cardId}/agent-runs`	Enumere las ejecuciones de una tarjeta. Vive solo por defecto; pasar `includeEnded=true` para la historia, lo más nuevo primero.
`GET /api/v1/agent-runs/{id}`	Leer una ejecución.
`PATCH /api/v1/agent-runs/{id}`	Actualizar, latir o finalizar una ejecución. Cada campo es opcional, por lo que `{}` es un simple latido del corazón.

Inicie la carrera y mantenga el id de la respuesta:

curl "$KANERA_PUBLIC_API_URL/api/v1/cards/$CARD_ID/agent-runs" \
  -X POST \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Implementing OAuth refresh","externalUrl":"https://github.com/acme/api/pull/482"}'

Luego informe el progreso y ciérrelo:

curl "$KANERA_PUBLIC_API_URL/api/v1/agent-runs/$RUN_ID" \
  -X PATCH \
  -H "Authorization: Bearer $KANERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"succeeded","summary":"Merged in PR 482; realtime suite green."}'

Los estados son running, blocked, succeeded, failed, cancelled, y stalled:

running y blocked son los dos estados vivos. uso blocked mientras el agente espera a una persona, como una pregunta o una aprobación; El chip de la tarjeta se vuelve ámbar.
succeeded, failed, y cancelled son terminales. El estado de un terminal finaliza la ejecución y la hace inmutable, por lo que cualquier fecha posterior PATCH regresa 409 con message: agent run has already ended.
stalled Lo establece Kanera, no usted, cuando una ejecución en vivo deja de latir durante quince minutos, por lo que un agente accidentado no puede dejar una tarjeta que muestre "funcionando" indefinidamente. Una ejecución detenida no finaliza: el agente aún puede cerrarla con un estado de terminal o establecer running para reanudar.

cada PATCH actualiza los latidos del corazón, incluido uno que no cambia nada, así que envíe un pozo de mantenimiento dentro de la ventana de quince minutos en un trabajo largo. Iniciar o actualizar un tablero de necesidades de ejecución Redactor acceso y una credencial con capacidad de escritura, exactamente como cualquier otra tarjeta de escritura. Las carreras también emiten el agentRun:started y agentRun:updated eventos de webhook.

Un agente conectado a través de OAuth se registra como el agente que actúa en nombre de su usuario: sus ejecuciones, comentarios y filas de actividad llevan el nombre del agente, y la persona para la que actúa recibe una notificación sobre lo que hizo. Una clave API personal utilizada por su propio script sigue actuando como su propietario.

Registrar un webhook desde una integración

Los administradores del espacio de trabajo pueden gestionar todos los puntos finales de webhook genéricos. Una credencial API no administrativa con capacidad de escritura o un agente OAuth interactivo también puede crear una cuando su usuario pertenece al espacio de trabajo; Kanera marca ese punto final scope: "connection"y solo los mismos administradores de conexión y espacio de trabajo pueden enumerarlo o administrarlo. Esto permite que un agente se suscriba a eventos del tablero sin recibir autorización de administrador del espacio de trabajo.

uso POST /api/v1/workspaces/{workspaceId}/webhooks para crear el punto final y guardar el único secret de la respuesta. El mismo recurso expone operaciones de lista, actualización, eliminación, rotación de secretos, historial de entrega y reintento de entrega fallida. Ver Ganchos web para el mapa de puntos finales y las reglas de firma.

Un flujo de integración confiable

llamar GET /api/v1/workspaces o GET /api/v1/boards para descubrir solo los recursos a los que puede acceder la credencial.
uso POST /api/v1/boards/{id}/open cuando necesite el tablero más sus listas, tarjetas, miembros, etiquetas y campos personalizados en una sola respuesta.
Almacene los identificadores devueltos para mutaciones de API. Los nombres son editables; una clave de tarjeta legible por humanos se puede resolver en la identificación de la tarjeta actual cuando una persona o un registro externo la proporciona.
Valide los cuerpos de escritura con el esquema de operación en Scalar u OpenAPI.
tratar 401 como autenticación no válida, 403 como acceso insuficiente o una puerta plana, 404 como datos faltantes o inaccesibles, 409 como un conflicto de estado, y 429 como señal para retroceder.
Registre la respuesta x-request-id en registros de integración sin credenciales de registro ni contenido confidencial.

Relaciones de tarjetas

Las relaciones conectan tarjetas en el mismo espacio de trabajo, incluso en todos sus tableros. direction lee de la tarjeta en la ruta: blocks significa que esta carta bloquea el objetivo, blocked_by significa que el objetivo bloquea esta carta, y relates_to no tiene orden requerido.

Método y camino	Propósito
`GET /api/v1/cards/{cardId}/relations`	Leer relaciones visibles y `hiddenBlockerCount`.
`POST /api/v1/cards/{cardId}/relations`	Añadir `{ "targetCardId": "<UUID>", "direction": "blocked_by" }`.
`DELETE /api/v1/cards/{cardId}/relations/{relationId}`	Eliminar una relación por su ID.

El detalle de la tarjeta incluye relations y hiddenBlockerCount; resúmenes de tarjetas exponen blockedByCount. Una tarjeta activa se bloquea mientras al menos un requisito previo está incompleto y no está archivado. uso filters: { blockedOnly: true } con POST /api/v1/work/cards/query devolver sólo tarjetas abiertas bloqueadas, o atRiskOnly: true para tarjetas abiertas cuyo bloqueador visible está vencido o vencido después de ellas. POST /api/v1/work/portfolio/query regresa blocked y atRisk recuentos por tablero y en sus totales.

Agregar una relación existente es idempotente. Se rechazan los autoenlaces, los enlaces entre espacios de trabajo, los ciclos de dependencia y una tarjeta completa como nuevo bloqueador. Las escrituras requieren acceso de edición a la tarjeta de ruta y a cualquier tarjeta que se bloquee, además de acceso de lectura a la otra tarjeta. Las relaciones inaccesibles se omiten en las lecturas; sus bloqueadores activos contribuyen sólo a hiddenBlockerCount.

Borrar el último bloqueador activo puede ejecutar automatizaciones y enviar notificaciones de transferencia. Reabrir o restaurar un bloqueador puede bloquear la tarjeta nuevamente. La finalización a través de la API sigue estando disponible sin la advertencia interactiva de la aplicación web. Ver Relaciones de tarjetas y bloqueo para el comportamiento del ciclo de vida.

Gráficos de dependencia

POST /api/v1/cards/dependency-graph lee el gráfico detrás de la vista Dependencias. Pase exactamente un alcance:

{ "boardId": "<board UUID>" }

Alternativamente pasar { "workspaceId": "<workspace UUID>" } o { "cardIds": ["<card UUID>"] }. Un ámbito de ID de tarjeta acepta entre 1 y 2000 UUID. Este POST es una lectura sin efectos secundarios.

La respuesta contiene resúmenes de tarjetas compactos, bordes, búsquedas de tablero/lista/etiqueta/personas, campos personalizados de caras de tarjetas y truncated. Cada tarjeta suma inScope y su canónico url. Cada tablero incluye canEdit para la autoridad de edición de dependencias de la persona que llama. un blocks El borde va desde sourceCardId (el requisito previo) para targetCardId (el dependiente); relates_to es simétrico.

El recorrido comienza con tarjetas de alcance abiertas y desarchivadas con relaciones, sigue los bordes de bloqueo en ambos sentidos a través de tableros legibles y se detiene en tarjetas completas. Los vecinos emparentados se incluyen a un salto de las semillas. Se omiten las tarjetas inaccesibles; blockedByCount todavía cuenta sus bloqueadores activos. El gráfico se detiene en 400 cartas y conjuntos. truncated: true; Reduzca el alcance cuando se necesite una cadena completa. Las credenciales del espacio de trabajo permanecen dentro de su espacio de trabajo.

Ver Vista de dependencias para saber cómo la aplicación presenta y edita estos datos. MCP devuelve una proyección ampliada orientada al agente en lugar de estos resúmenes compactos.

Modelo de tablero y espacio de trabajo.

La API de Kanera representa ambos modelos orientados al usuario:

Un espacio de trabajo estándar contiene varios tableros.
Se devuelve un tablero independiente con kind: "board" por puntos finales que exponen su contenedor de respaldo, pero los usuarios lo experimentan como un tablero independiente.
Los tableros contienen cartas.
Las listas, etiquetas y campos personalizados pertenecen únicamente a un tablero independiente o se comparten en todos los tableros de un espacio de trabajo estándar.
Los puntos finales de asignación pueden devolver tarjetas asignadas en todos los tableros del espacio de trabajo.
Los tableros privados solo son visibles donde la clave API tiene acceso.
Una clave personal puede ver tableros en los espacios de trabajo a los que su propietario tiene acceso.
Una clave de espacio de trabajo solo puede ver los tableros dentro de su único espacio de trabajo.

Esto es importante al crear integraciones. Utilice un tablero independiente cuando su esquema deba permanecer independiente. En un espacio de trabajo, reutilice las listas y los campos existentes para que los informes, las consultas de asignación y la agregación de campos personalizados se mantengan coherentes. La interfaz de usuario de trabajo global puede abarcar todos los tableros a los que puede acceder la persona que ha iniciado sesión, mientras que una clave API del espacio de trabajo permanece limitada a su único espacio de trabajo.

Paginación y errores.

Enumere los puntos finales que admiten el uso de paginación:

Parámetro	Significado
`limit`	Número de registros a devolver.
`before`	Filtro de estilo cursor para registros antes de una marca de tiempo.

Los errores devuelven JSON con:

campo	Significado
`code`	Código de error estable.
`message`	Mensaje de error legible por humanos.
`issues`	Detalles de validación opcionales.

Utilice el código de estado HTTP y el código de error juntos cuando decida si desea volver a intentarlo, corregir la entrada o pedirle a un administrador que actualice el acceso.

Ganchos web

Los webhooks permiten que los sistemas externos reaccionen cuando el trabajo cambia en Kanera. Ver Ganchos web para configuración, verificación de entrega y la lista completa de tipos de eventos de webhook admitidos.

Si el objetivo es publicar la actividad de la tarjeta en un canal de chat del equipo, no necesita crear nada: use Destinos de chat para Slack, Discord, Telegram o Zulip.

Enlaces externos

Los enlaces externos permiten que las integraciones almacenen asignaciones duraderas entre registros de Kanera y registros en otro sistema.

Utilice enlaces externos cuando necesite que los trabajos de sincronización sean idempotentes. Por ejemplo, una sincronización de Trello puede recordar qué tarjeta Kanera se asigna a qué tarjeta Trello sin incluir metadatos de integración ocultos en la descripción de la tarjeta.

Recomendaciones de seguridad

Utilice una clave API por integración.
Utilice el alcance más bajo que funcione.
Almacene claves y secretos de webhooks en un administrador de secretos.
Rote claves y secretos de webhooks cuando las personas se vayan o los sistemas cambien.
No coloque claves API en Scratchpad, Notas, tarjetas, comentarios, control de fuente, registros o capturas de pantalla.
Verifique las firmas de webhooks antes de procesar cargas útiles.
Haga que los controladores de webhook sean idempotentes porque se pueden volver a intentar las entregas.
Registre suficientes ID de eventos y solicitudes para depurar el comportamiento de sincronización sin registrar secretos.

que puedes construir​

Clientes oficiales​

Referencia API​

Utilice la referencia del punto final​

Grupos de puntos finales​

Elija un tipo de clave API​

Requisitos del plan​

Límites de tarifas​

Crear una clave API personal​

Claves personales de solo lectura​

Crear una clave API de tablero o espacio de trabajo​

Ámbitos clave de la API del espacio de trabajo​

Autenticación​

OAuth para agentes de IA​

URL base y versiones​

Primeras solicitudes​

Administrar separadores de tablero​

Administrar Hasta el siguiente pedido​

Adjuntar y leer archivos​

Capturar al bloc de notas​

Ver tarjetas y configurar recordatorios​

Seguimiento del trabajo en vuelo de un agente​

Registrar un webhook desde una integración​

Un flujo de integración confiable​

Relaciones de tarjetas​

Gráficos de dependencia​

Modelo de tablero y espacio de trabajo.​

Paginación y errores.​

Ganchos web​

Enlaces externos​

Recomendaciones de seguridad​

Páginas relacionadas​