Kanera-API

Met de openbare API van Kanera kunt u integraties bouwen rond hetzelfde werk dat uw team in de app beheert: werkruimten, borden, kaarten, lijsten, bordscheidingstekens, opmerkingen, checklists, notities, bijlagen, labels, aangepaste velden, opdrachten, gerangschikte wachtrijen voor volgende, activiteiten en externe links.

Gebruik de API wanneer de Kanera verbinding moet maken met een ander systeem, een interne workflow moet aandrijven, gegevens moet migreren, rapporten moet bouwen of een andere tool Kanera moet laten maken en bijwerken.

Wat je kunt bouwen

Veelvoorkomende API-gebruiksscenario's zijn onder meer:

• Synchroniseer Kanera-kaarten met een andere werktracker.
• Maak kaarten op basis van formulieren, ondersteuningstickets, chatberichten of CRM-records.
• Bouw aangepaste rapportagedashboards op basis van borden, opdrachten, labels, aangepaste velden en activiteiten.
• Importeer werk in Kanera vanuit een ander systeem.
• Houd externe gegevens gekoppeld aan Kanera-kaarten of -notities.
• Voeg opmerkingen of statusupdates toe vanuit een andere tool.
• Upload bestanden en voeg ze toe aan kaarten of notities.
• Lees de activiteitengeschiedenis voor audit, rapportage of automatisering.

Kanera-integraties kunnen zich richten op zelfstandige borden of werkruimten. Een zelfstandig bord heeft zijn eigen lijsten, labels en aangepaste velden. Een werkruimte deelt deze bronnen met alle boards, waardoor cross-board rapportage en synchronisatieworkflows gemakkelijker consistent kunnen worden gehouden.

Officiële klanten

Je hoeft niet vanaf te starten curl. Twee first-party clients gebruiken dezelfde API:

Klant	Installeren	Gebruik het voor
Kanera CLI	npm install --global @kanera/cli	Terminalgebruik, shellscripts en AI-agents die opdrachten kunnen uitvoeren.
Typescript SDK	npm install @kanera/sdk	TypeScript- en JavaScript-integraties. Geen runtime-afhankelijkheden; draait op Node, Bun, Deno,workers en browsers.

De SDK heeft een MIT-licentie, dus als u deze in uw eigen toepassing insluit, ontstaan er geen vragen over het licentiebeleid. Gebruik de REST-eindpunten rechtstreeks voor elke andere taal.

API-referentie

Kanera REST API bevindt zich op:

https://api.kanera.app

Gedetailleerde referentie op eindpuntniveau is beschikbaar op:

https://api.kanera.app/docs

De openbare API-service bevat de referentie op eindpuntniveau:

Pad	Gebruik
/docs	Interactieve Scalaire API-referentie.
/swagger	Swagger UI-referentie.
/openapi.json	OpenAPI-document voor het genereren en bewerken van SDK's.

Voor Kanera, open:

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

Gebruik deze pagina als handleiding om aan de slag te gaan en gebruik vervolgens de API-referentie voor exacte eindpuntpaden, verzoekteksten, antwoordschema's en beschikbare webhookgebeurtenistypen.

Gebruik de eindpuntreferentie

Openen Scalair voor de primaire eindpuntreferentie. Bij elke bewerking worden de methode en het pad, het vereiste bereik, de pad- en queryparameters, het aanvraagschema, het antwoordschema en de foutreacties weergegeven. Gebruik Autoriseren om een dragertoken op te geven wanneer u een verzoek wilt proberen.

Gebruik Swagger-gebruikersinterface wanneer uw tool of workflow rond Swagger is gebouwd. Downloaden OpenAPI JSON voor het genereren van SDK, vraag om validatie of importeer de API in een andere client.

Het OpenAPI-document is de bron van de waarheid. Kopieer een voorbeeld uit de referentie in plaats van de hoofdtekst van een verzoek te raden, en test schrijf- of verwijderbewerkingen op de beoogde werkruimte voordat u ze automatiseert.

Eindpuntgroepen

Groep	Typische operaties
Werkplekken en borden	Ontdek toegankelijk werk, open de volledige bordstatus, beheer leden en gasten en maak borden aan of herschik ze.
Lijsten, scheidingstekens en kaarten	Werk maken, bijwerken, positioneren, verplaatsen, voltooien, archiveren, dupliceren en in bulk bewerken.
Notities en bijlagen	Maak geneste notities, beheer vergrendelingen en backlinks, upload bestanden rechtstreeks of via een eenmalige uploadlink en lees de bytes van een bijlage.
Kladblok	Lees de privé-kladblokpagina's van de beller en leg snelle taken vast in een Inbox-pagina. Alleen persoonlijke inloggegevens.
Velden en labels	Beheer aangepaste velden, opties en herbruikbare kaartlabels op werkruimteniveau.
Opmerkingen en activiteit	Lees kaartfeeds, schrijf opmerkingen en reacties en bekijk de bestuursactiviteiten.
Volgende prioriteiten	Ontdek leesbare wachtrijen, vermeld de teamvolgorde en voeg gerangschikte kaarten toe, verplaats of verwijder deze.
Volgende	Bekijk of stop met het bekijken van kaarten en borden, stel uw privékaartherinneringen in, wis of vermeld deze en peil uw inbox met meldingen. Alleen persoonlijke inloggegevens.
Agent vlucht	Kondig aan dat een agent aan een kaart werkt, hartslag terwijl deze wordt uitgevoerd en noteer hoe deze is geëindigd.
Zoeken en externe links	Zoek toegankelijke inhoud en onderhoud idempotente toewijzingen aan records in andere systemen.
Webhaken	Registreer en beheer eindpunten, inspecteer of probeer leveringen opnieuw en ontvang ondertekende wijzigingsgebeurtenissen zonder polling.

Kies een API-sleuteltype

Kanera heeft twee API-sleuteltypen. Ze authenticeren op dezelfde manier, maar hun toegangsmodel is anders.

Sleuteltype	Creëer het van	Gebruik het wanneer	Toegangsmodel
Persoonlijke API-sleutel	Profielinstellingen -> API-sleutels	U verbindt uw eigen script, CLI of MCP-client en wilt dat het werkt op alle boards waartoe u persoonlijk toegang hebt.	Handelt als u, in elke werkruimte en op elk bord waartoe u toegang hebt, en respecteert uw rol op elk bord. Het is Lees of Schrijf De reikwijdte beperkt wat het binnen die toegang mag doen. Het kan geen werkruimtebeheerdersacties uitvoeren.
Werkruimte of bord API-sleutel	Werkruimte-instellingen -> API of Bordinstellingen -> API	U zet een teamintegratie, serviceaccount, webhookproducent, synchronisatietaak of automatisering op voor één werkruimte of zelfstandig bord.	Gericht op die werkruimte of op een zelfstandig bord. Het is Lees, Schrijf, of Beheerder scope bepaalt wat de integratie kan doen.

Gebruik een persoonlijke sleutel voor workflows die eigendom zijn van de gebruiker. Gebruik een werkruimte of bordsleutel met bereik voor gedeelde of productie-integraties die eigendom moeten zijn van, gerouleerd en gecontroleerd moeten worden met de bestemming.

Planvereisten

Persoonlijke API-sleutels en interactieve AI-agentverbindingen werken door elk plan, inclusief gehost gratis. Ze fungeren als een huidige gebruiker, zodat ze precies de borden bereiken die de gebruiker kan openen, zowel in Free- als Pro-organisaties.

Werkruimte- en bord API-sleutels, onbeheerde OAuth-serviceagenten, webhooks en chatbestemmingen hebben Pro of de 30-dagen Pro-proefversie. Ze worden namens de organisatie uitgevoerd zonder dat iemand zich heeft aangemeld. Ze zijn dus niet beschikbaar op gehost Free, waar dit wordt uitgelegd op de pagina met werkruimte-instellingen in plaats van dat het aanmaakformulier wordt weergegeven. Verzoeken geblokkeerd door een planlimietretour 403 met de foutcode PLAN_LIMIT, zodat een integratie een planprobleem kan onderscheiden van een toestemmingsprobleem.

Het creëren van werkruimte- of bord-API-sleutels, OAuth-clients en behoeften aan chatbestemmingen werkruimte beheerder toestemming. Beheerders beheren ook elk webhookeindpunt in een werkruimte; een API-referentie of interactieve OAuth-agent met schrijfmogelijkheid kan eindpunten registreren die zijn gericht op zijn eigen verbinding wanneer de gebruiker lid is van de werkruimte. Voor persoonlijke API-sleutels hoeft geen werkruimterol te worden aangemaakt.

De poort is niet alleen op de schepping gericht. Wanneer een gehoste organisatie overstapt op Gratis, trekt Kanera de actieve werkruimte- en board-API-sleutels in, waardoor ook de daarop gebouwde OAuth-serviceagenten worden uitgeschakeld, en /api/v1 wijst ze op verzoek af, dus een sleutel die elders overleeft, kan nog steeds niet worden gebruikt. Persoonlijke API-sleutels en interactieve agentverbindingen blijven werken. Webhook-eindpunten en chatbestemmingen worden gepauzeerd door dezelfde downgrade. Door terug te upgraden naar Pro worden de sleutels en eindpunten hersteld die door de downgrade zijn geraakt.

Tarieflimieten

Verzoeken van API-sleutels en AI-agents, zowel via REST als MCP, zijn beperkt per gebruiker, binnen de abonnementslimieten van de organisatie die eigenaar is van het bord waartoe toegang wordt verkregen:

De organisatie van het bestuur	Per seconde	Per minuut
Gratis gehost	5	60
Gehoste Pro- of Pro-proefversie	20	400
Zelf gehost	20	400 (configureerbaar)

Een gebruiker die tot zowel een Free- als een Pro-organisatie behoort, krijgt de limieten van elke organisatie op zijn eigen borden. Aanvragen boven de limiet worden niet meteen geweigerd: maximaal 10 wachten in een wachtrij, maximaal 10 seconden, en worden geserveerd als capaciteitsvrijgave. Alleen verzoeken buiten die wachtrij worden ontvangen 429 met een Retry-After koptekst. De CLI-, SDK- en MCP-server gaan automatisch uit en proberen het opnieuw.

Zelf-hostende operators kunnen de limieten wijzigen met PUBLIC_API_KEY_RATE_LIMIT_PER_SECOND, PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE, PUBLIC_API_RATE_LIMIT_QUEUE_SIZE, en PUBLIC_API_RATE_LIMIT_QUEUE_MAX_WAIT_MS. Zie Webhaken voor het volledige downgradegedrag.

Maak een persoonlijke API-sleutel aan

1. Openen Profielinstellingen.
2. Ga naar API-sleutels tabblad.
3. Maak een persoonlijke API-sleutel aan.
4. Kies Alleen-lezen of Lezen en schrijven.
5. Voeg optioneel een private label toe, zodat u kunt herkennen waar de sleutel wordt gebruikt.
6. Kopieer het geheim wanneer het wordt weergegeven.

Persoonlijke sleutels zijn altijd gekoppeld aan de gebruiker die ze heeft aangemaakt. Ze volgen de echte boardtoegang en rol van de eigenaar, en de activiteit wordt weergegeven als die van de eigenaar. Er is geen beheerbereik: een persoonlijke sleutel kan nooit werkruimtebeheer uitvoeren, ongeacht de rol van de eigenaar.

Alleen-lezen persoonlijke sleutels

Een persoonlijke sleutel is lezen en schrijven tenzij u anders kiest, wat u krijgt van een bestaande sleutel of een ongewijzigde creatiestroom.

Kies Alleen-lezen wanneer de inloggegevens ergens heen gaan waar u niet naar kijkt: een AI-agent, een rapportagetaak, een CI-controle, een dashboard. Een alleen-lezen sleutel kan weergeven, lezen, zoeken en rapporteren, en Kanera weigert elke mutatie 403 en de foutcode FORBIDDEN. Omdat de weigering plaatsvindt bij de API en niet bij de client, kan een agent die zich misdraagt ​​of prompt wordt geïnjecteerd, uw werk nog steeds niet veranderen.

Het bereik ligt vast wanneer de sleutel wordt gemaakt. Om deze te wijzigen, maakt u een nieuwe sleutel aan en trekt u de oude in.

Het geheim wordt één keer getoond. Sla het op in uw lokale geheime manager, MCP-clientconfiguratie of omgevingsvariabelen.

Maak een werkruimte of bord-API-sleutel

1. Open de werkruimte of het zelfstandige bord.
2. Ga naar Werkruimte-instellingen -> API of Bordinstellingen -> API.
3. Maak een API-sleutel voor de werkruimte.
4. Kies de kleinste scope die bij de integratie past.
5. Kopieer het geheim wanneer het wordt weergegeven.

Werkruimte API-sleutels zijn werkruimtegericht. Een sleutel heeft alleen toegang tot bronnen in de werkruimte waar deze is gemaakt en waar de maker ervan nog steeds toegang heeft.

Het geheim wordt één keer getoond. Bewaar het in de geheime manager of omgevingsvariabelen van uw integratie.

Werkruimte API sleutelbereiken

Reikwijdte	Gebruik het wanneer
Lees	De integratie hoeft alleen Kanera-gegevens te lezen, zoeken, rapporteren of exporteren.
Schrijf	De integratie moet werk maken of bijwerken, zoals kaarten, opmerkingen, labels, toegewezen personen, aangepaste veldwaarden, notities of bijlagen.
Beheerder	Voor de integratie zijn openbare API-bewerkingen op beheerdersniveau vereist, indien ondersteund. Gebruik dit spaarzaam.

Lees, Schrijf, en Beheerder van toepassing op werkruimte- en bordsleutels. Persoonlijke sleutels kiezen tussen Lees en Schrijf alleen, en neem bovendien altijd de machtigingen op bordniveau van de eigenaar over.

Gebruik afzonderlijke API-sleutels voor afzonderlijke integraties. Dit maakt het gemakkelijker om toegang in te trekken, te rouleren en te controleren. Geef voor gedeelde systemen de voorkeur aan werkruimtesleutels, zodat de toegang niet gebonden is aan de persoonlijke tool van één persoon.

Authenticatie

Verzend de API-sleutel als een dragertoken:

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

Kanera API-sleutels gebruiken voorvoegsels voor de omgeving:

Voorvoegsel	Milieu
kanera_live_...	Productie
kanera_stg_...	Staging
kanera_dev_...	Ontwikkeling
kanera_test_...	Testen

Persoonlijke sleutels dragen een u markering na het leveranciersvoorvoegsel, dus kanera_u_live_... is een persoonlijke sleutel en kanera_live_... is een werkruimte- of bordsleutel. Beide authenticeren op dezelfde manier.

Ontbrekende of ongeldige sleutels retourneren 401. Geldige sleutels zonder toestemming voor het retourneren van een resource of bewerking 403 — inclusief een schrijfpoging met een leessleutel.

OAuth voor AI-agents

Kanera ondersteunt OAuth 2.0, zodat een compatibele AI-agent verbinding kan maken met Kanera MCP via browsertoestemming of een serviceverbinding in plaats van een API-sleutel op te slaan.

Een OAuth-verbinding is voor MCP; het is geen algemene openbare API-referentie. Gebruik een persoonlijke API-sleutel, werkruimte- of board-API-sleutel wanneer uw eigen integratie moet worden aangeroepen /api/v1 direct.

Er zijn drie OAuth-paden:

• Interactieve agenten gebruik de autorisatiecodestroom met PKCE. Een persoon keurt de verbinding eenmaal goed in de browser en de agent fungeert als die gebruiker. Dit is hoe compatibele MCP-clients zoals Claude, ChatGPT, Copilot en Codex verbinding maken zonder een API-sleutel.
• Apparaatclients gebruik de apparaatautorisatietoekenning (urn:ietf:params:oauth:grant-type:device_code). De client toont een korte code, iemand keurt deze goed in een browser op elk apparaat en de client vraagt ​​naar tokens. Gebruik dit voor een CLI of headless client die geen browseromleiding kan ontvangen. Zie de referentie voor apparaatautorisatie.
• Onbeheerde agenten gebruik de client_credentials verlenen. U maakt een klant-ID en geheim aan Werkruimte-instellingen -> API en wissel ze in voor tokens met een korte levensduur, zonder browserstap. Gebruik deze voor CI-, cron- of server-side agents.

Zie Sluit een AI-agent aan voor installatie, scopes en verbindingsbeheer. Auteurs van aangepaste OAuth-clients kunnen de protocoldetails vinden in de MCP technische referentie.

Basis-URL en versiebeheer

REST-eindpunten leven onder /api/v1 op de openbare API-service.

Bijvoorbeeld:

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

Operationele helperpaden zoals /docs, /swagger, /openapi.json, ondertekende media-URL's en detectie van webhookgebeurtenissen kunnen zich buiten de /api/v1 voorvoegsel. Behandel ondertekende media-URL's die door de API worden geretourneerd als ondoorzichtige URL's en gebruik ze zoals opgegeven.

Eerste verzoeken

Controleer wie de referentie fungeert. GET /api/v1/session retourneert de gebruiker, organisatie, soort inloggegevens en scope (read betekent dat elke wijziging wordt geweigerd), plus die van de gebruiker timeZone en today, de huidige datum in die zone, zodat een klant 'vandaag' of 'morgen' kan oplossen op de manier waarop Kanera vervaldatums stempelt:

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

Geef een overzicht van de werkruimten waartoe de API-sleutel toegang heeft:

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

Maak vervolgens een lijst van borden in een werkruimte:

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

Open een bord om het bord, werkruimtelijsten, bordscheidingstekens, zichtbare kaarten, leden, labels en aangepaste velden op te halen die nodig zijn om werk weer te geven of te synchroniseren:

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

Maak een kaart:

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"}'

Een creatie kan ook worden ingesteld labelIds, assigneeIds, dueDateLocalDate (YYYY-MM-DD), en dueDateSlot in dezelfde schrijfwijze, zodat de kaart volledig beschreven arriveert en de labelautomatiseringen één keer worden uitgevoerd.

Creëer meerdere kaarten tegelijk, tot 50 per aanvraag op één bord. Elke kaart noemt zijn eigen lijst en komt onderaan de lijst terecht in de volgorde van de verzoeken:

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\"}]}"

Elke kaart wordt gecontroleerd voordat er een wordt aangemaakt, dus een onbekende lijst, label of verantwoordelijke wijst het hele verzoek af met een 400 dat de vermelding een naam geeft, zoals cards[1]: one or more label ids are invalid. Elke kaart activeert vervolgens dezelfde automatiseringen, meldingen en webhooks als één enkele creatie.

Kaartreacties omvatten het onveranderlijke workspaceId, ondoorzichtig organisationKey, positief number, momenteel leesbaar voor mensen key zoals PROJ-123en schone browser url. Een werkruimtevoorvoegsel kan veranderen, maar het kaartnummer niet.

Los een huidige of historische kaartsleutel op voordat u een op ID gebaseerd mutatie-eindpunt aanroept:

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

De resolutie is hoofdlettergevoelig en retourneert de huidige ID, werkruimte, bord, lijst, nummer, sleutel en browser-URL van de kaart. De organisatiesleutel is de ondoorzichtige waarde die door Kanera wordt geretourneerd, en niet de naam van een organisatie of slug. Ontbrekende en ontoegankelijke kaarten komen beide terug 404.

Een kaart bijwerken:

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"}'

Voeg een opmerking toe:

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."}'

Vervang de labels of houders van de kaart door een exacte set:

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\"]}"

Deze twee PUT operaties vervangen de hele set. Stuur een lege array om deze te wissen; gebruik de gedocumenteerde bulkbewerkingen voor toevoegen/verwijderen wanneer u de semantiek van geselecteerde kaarten wilt patchen.

Vul een kaart in:

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}'

Beheer bordscheidingstekens

Een scheidingsteken is een item dat eigendom is van het bord, een titel heeft en optioneel gekleurd is in de gemengde volgorde van kaarten en scheidingstekens in een workflowlijst. Maak er een op een exact getypt anker:

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\"}}"

Update de titel of kleur met PATCH /api/v1/separators/{id}, verplaats het met POST /api/v1/separators/{id}/moveen verwijder het met DELETE /api/v1/separators/{id}. Verplaats lichamen noemen de bestemming listId en geef er precies één beforeItem of afterItem; het artikel kan een zijn { "type": "card", "id": "..." } of { "type": "separator", "id": "..." } referentie. EEN null afterItem betekent de bovenkant en een null beforeItem betekent de bodem. Als u een scheidingsteken verwijdert, blijven de kaarten ongewijzigd.

Beheer volgende bestelling

De API geeft dezelfde gerangschikte wachtrijen weer die worden gebruikt door Home, My Cards en Team Cards:

Eindpunt	Gebruik
GET /api/v1/work/priority-targets	Maak een lijst van de gebruikers van wie de wachtrijen door de referentie kunnen worden gelezen.
GET /api/v1/work/priorities	Lees elke toegestane wachtrij in één antwoord.
GET /api/v1/work/priorities/{userId}	Lees één wachtrij in rangorde.
POST /api/v1/work/priorities/{userId}/cards	Voeg een toegewezen actieve kaart toe op een verankerde positie.
POST /api/v1/card-priorities/{id}/move	Verplaats één wachtrij-item voor of na een ander zichtbaar item.
DELETE /api/v1/card-priorities/{id}	Verwijder de vermelding zonder de kaart te wijzigen.

Persoonlijke inloggegevens kunnen altijd hun eigen wachtrij lezen. Het lezen van de wachtrij van iemand anders vereist effectieve beheerdersbevoegdheid in een gedeelde werkruimte, en voor schrijfbewerkingen zijn ook schrijfgegevens en machtigingen voor de doelkaart vereist. Gebruik de invoer-ID's die door de wachtrij worden geretourneerd als verplaatsingsankers; rangen zijn presentatiewaarden, geen mutatie-ID's.

Bestanden bijvoegen en lezen

POST /api/v1/cards/{id}/attachments duurt een meerdelige upload. Wanneer het bestand zich ergens bevindt waar de beller niet rechtstreeks van kan streamen, zoals de sandbox van een AI-agent, maak dan een eenmalige uploadlink aan en PUT de onbewerkte bytes ervan:

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"

• De link werkt één keer, verloopt na 15 minuten en werkt niet meer als de sleutel waarmee de link is gemaakt, wordt ingetrokken.
• Kanera slaat het bestand op onder de naam en het type dat is vastgelegd toen de link werd gemaakt, en leidt het type af van de extensie als u dit weglaat mimeType. Logbestanden (.log, .out, .jsonlen dergelijke) worden opgeslagen als platte tekst.
• Voor het maken van een koppeling zijn schrijfgegevens en Editor-toegang tot de kaart vereist. Opslaglimieten worden gecontroleerd wanneer de link wordt gemaakt en wanneer het bestand arriveert.
• Het uploadantwoord is de nieuwe bijlage en iedereen die de kaart bekijkt, ziet deze onmiddellijk verschijnen.

Lees de bytes van een bijlage met GET /api/v1/cards/{id}/attachments/{attachmentId}/content. Het ondersteunt Range verzoeken, en ?variant=cover (tot 1200px) of ?variant=thumbnail (400px) retourneert de JPEG-kopieën die Kanera maakt van PNG-, JPEG-, GIF- en WebP-afbeeldingen.

Leg vast op het Kladblok

POST /api/v1/scratchpad/capture voegt een open taak toe aan de privégegevens van de beller Kladblok, op de eerste pagina getiteld pageTitle (standaard Inbox), en maakt de pagina wanneer deze ontbreekt:

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 vermeldt elke pagina met de inhoud ervan, en PATCH /api/v1/scratchpad/notes/{id} vervangt een pagina. Passeer de updatedAt jij leest als baseUpdatedAt ontvangen 409 SCRATCHPAD_STALE in plaats van de sindsdien aangebrachte bewerkingen te overschrijven. Het Kladblok is van één persoon, dus werkruimte API-sleutels ontvangen 403; gebruik een persoonlijke sleutel of een OAuth-verbinding.

Bekijk kaarten en stel herinneringen in

De Volgende eindpunten beheren de eigen abonnementen van de beller, zodat API-sleutels in de werkruimte worden ontvangen 403; gebruik een persoonlijke sleutel of een OAuth-verbinding. Voor het wijzigen ervan is een inloggegevens nodig die geschikt zijn voor schrijven, maar alleen leestoegang tot de kaart.

Eindpunt	Gebruik
GET /api/v1/cards/{id}/follow	Of je nu naar de kaart kijkt, en naar je herinnering erop.
PUT / DELETE /api/v1/cards/{id}/watch	Bekijk of stop met het bekijken van een kaart. Retourneert dezelfde status als follow.
PUT / DELETE /api/v1/boards/{id}/watch	Kijk of stop met kijken naar een bord.
PUT /api/v1/cards/{id}/reminder	Stel uw herinnering in: {"remindAt": "2026-10-16T15:00:00+01:00"}.
DELETE /api/v1/cards/{id}/reminder	Wis uw herinnering.
GET /api/v1/reminders	Uw openstaande herinneringen, zo snel mogelijk eerst. ?status=all inclusief degenen die al hebben geschoten.
GET /api/v1/notifications	Poll uw notificatie-inbox vooruit vanaf een cursor. Zie hieronder.

remindAt is een ISO-momenteel met een offset, in de toekomst en maximaal 56 dagen (acht weken) vooruit. Je hebt één herinnering per kaart, dus als je deze opnieuw instelt, wordt deze vervangen en opnieuw ingeschakeld. Uw andere open sessies worden onmiddellijk bijgewerkt. Er worden noch kijken, noch herinneringen weergegeven in de activiteit van de kaart. Zie Herinneringen.

GET /api/v1/notifications is voor een script of agent die geen webhooks kan ontvangen, zoals een script of agent die op een laptop draait. Het retourneert dezelfde rijen als uw meldingenlade (antwoorden, vermeldingen, opdrachten en wijzigingen op kaarten die u bekijkt of waaraan u bent toegewezen), de oudste eerst. Noem het een keer zonder since voor de laatste rijen en geef vervolgens de antwoorden door cursor terug als since, terwijl hij herhaalt hasMore is true, om alleen te krijgen wat nieuw is. Elke rij bevat één regel summary, de card sleutel en URL, de actor, en een commentExcerpt voor commentaar. Rijen verschijnen een paar seconden na de gebeurtenis. Een AI-agentverbinding ziet geen meldingen die door zijn eigen schrijfbewerkingen worden veroorzaakt, tenzij u deze toevoegt includeSelf=true, en opiniepeilingen markeren nooit iets als gelezen.

Volg het werk van een agent tijdens de vlucht

Wanneer de beller een AI-agent is in plaats van een synchronisatietaak, kan hij het werk dat hij doet op een kaart aankondigen. Kanera toont vervolgens een live-chip op de kaarttegel, geeft de kaartgegevens weer en registreert kaartactiviteitsrijen voor het begin en het einde - zodat iemand kan zien dat er iets gebeurt en wie het doet, zonder op het resultaat te wachten.

Eindpunt	Gebruik
POST /api/v1/cards/{cardId}/agent-runs	Begin een run. Lichaam neemt title (vereist), summary, en externalUrl.
GET /api/v1/cards/{cardId}/agent-runs	Maak een lijst van de runs van een kaart. Leef alleen standaard; doorgang includeEnded=true voor geschiedenis, nieuwste eerst.
GET /api/v1/agent-runs/{id}	Eén run lezen.
PATCH /api/v1/agent-runs/{id}	Update, hartslag of voltooi een run. Elk veld is optioneel, dus {} is een blote hartslag.

Start de run en houd de id uit de reactie:

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"}'

Rapporteer vervolgens de voortgang en sluit het af:

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."}'

Statussen zijn running, blocked, succeeded, failed, cancelled, en stalled:

• running en blocked zijn de twee levende staten. Gebruik blocked terwijl de agent op een persoon wacht, zoals een vraag of een goedkeuring; de chip van de kaart wordt oranje.
• succeeded, failed, en cancelled zijn terminaal. Een terminalstatus beëindigt de run en maakt deze onveranderlijk, dus later PATCH retourneert 409 met message: agent run has already ended.
• stalled wordt ingesteld door Kanera, niet door jou, wanneer een live run vijftien minuten lang stopt met kloppen, zodat een gecrashte agent een kaart met de melding "werkend" niet voor onbepaalde tijd kan laten staan. Een vastgelopen run wordt niet beëindigd: de agent kan deze nog steeds afsluiten met een terminalstatus of ingesteld running hervatten.

Elke PATCH verfrist de hartslag, inclusief een die niets verandert, dus stuur een keep-alive goed binnen het venster van vijftien minuten voor een lange klus. Het starten of bijwerken van een run heeft een bord nodig Redacteur toegang en schrijfmogelijkheden, precies zoals elke andere schrijfkaart. Runs stoten ook de agentRun:started en agentRun:updated webhook-evenementen.

Een agent verbonden via OAuth wordt geregistreerd als de agent die namens de gebruiker optreedt: de rijen runs, opmerkingen en activiteiten dragen de naam van de agent, en de persoon voor wie hij optreedt, wordt op de hoogte gesteld van wat hij heeft gedaan. Een persoonlijke sleutel API die door uw eigen script wordt gebruikt, fungeert nog steeds als eigenaar.

Registreer een webhook vanuit een integratie

Werkruimtebeheerders kunnen elk generiek webhookeindpunt beheren. Een API-referentie of interactieve OAuth-agent die niet door de beheerder kan worden geschreven, kan er ook een maken wanneer de gebruiker tot de werkruimte behoort; Kanera markeert dat eindpunt scope: "connection", en alleen dezelfde verbindings- en werkruimtebeheerders kunnen deze weergeven of beheren. Hierdoor kan een agent zich abonneren op boardgebeurtenissen zonder machtiging voor de werkruimtebeheerder te ontvangen.

Gebruik POST /api/v1/workspaces/{workspaceId}/webhooks om het eindpunt te maken en het eenmalige op te slaan secret uit de reactie. Dezelfde bron maakt lijst-, update-, verwijder-, geheime rotatie-, bezorgingsgeschiedenis en mislukte bezorgpogingen zichtbaar. Zie Webhaken voor de eindpuntkaart en handtekeningregels.

Een betrouwbare integratiestroom

1. Bel GET /api/v1/workspaces of GET /api/v1/boards om alleen bronnen te ontdekken waartoe de referentie toegang heeft.
2. Gebruik POST /api/v1/boards/{id}/open wanneer je het bord plus de lijsten, kaarten, leden, labels en aangepaste velden in één reactie nodig hebt.
3. Bewaar geretourneerde ID's voor API-mutaties. Namen zijn bewerkbaar; een voor mensen leesbare kaartsleutel kan worden omgezet in de huidige kaart-ID wanneer een persoon of extern record er een levert.
4. Valideer schrijfteksten op basis van het bewerkingsschema in Scalar of OpenAPI.
5. Behandel 401 als ongeldige authenticatie, 403 als onvoldoende toegang of een planpoort, 404 als ontbrekende of ontoegankelijke gegevens, 409 als een staatsconflict, en 429 als signaal om zich terug te trekken.
6. Noteer het antwoord x-request-id in integratielogboeken zonder registratie van inloggegevens of gevoelige inhoud.

Kaartrelaties

Relaties verbinden kaarten in dezelfde werkruimte, ook over de grenzen heen. direction leest van de kaart in het pad: blocks betekent dat deze kaart het doelwit blokkeert, blocked_by betekent dat het doelwit deze kaart blokkeert, en relates_to heeft geen vereiste volgorde.

Methode en pad	Doel
GET /api/v1/cards/{cardId}/relations	Lees zichtbare relaties en hiddenBlockerCount.
POST /api/v1/cards/{cardId}/relations	Toevoegen { "targetCardId": "<UUID>", "direction": "blocked_by" }.
DELETE /api/v1/cards/{cardId}/relations/{relationId}	Verwijder een relatie op basis van de ID.

Kaartdetail omvat relations en hiddenBlockerCount; kaartsamenvattingen blootleggen blockedByCount. Een actieve kaart wordt geblokkeerd terwijl ten minste één vereiste onvolledig is en niet wordt gearchiveerd. Gebruik filters: { blockedOnly: true } met POST /api/v1/work/cards/query alleen geblokkeerde open kaarten teruggeven, of atRiskOnly: true voor open kaarten waarvan de zichtbare blokkeerder te laat is of erna komt. POST /api/v1/work/portfolio/query retourneert blocked en atRisk telt per bord en in zijn totalen.

Het toevoegen van een bestaande relatie is idempotent. Zelfkoppelingen, koppelingen tussen werkruimten, afhankelijkheidscycli en een voltooide kaart als nieuwe blokkering worden afgewezen. Voor schrijfbewerkingen is bewerkingstoegang tot de padkaart en de kaart die wordt geblokkeerd vereist, plus leestoegang tot de andere kaart. Ontoegankelijke relaties worden weggelaten uit lezingen; hun actieve blokkers dragen er alleen maar aan bij hiddenBlockerCount.

Door de laatste actieve blokkering te wissen, kunnen automatiseringen worden uitgevoerd en overdrachtsmeldingen worden verzonden. Het heropenen of herstellen van een blocker kan de kaart opnieuw blokkeren. Voltooiing via de API blijft beschikbaar zonder de interactieve waarschuwing van de webapp. Zie Kaartrelaties en blokkering voor levenscyclusgedrag.

Afhankelijkheidsgrafieken

POST /api/v1/cards/dependency-graph leest de grafiek achter de weergave Afhankelijkheden. Geef precies één bereik door:

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

Alternatief passeren { "workspaceId": "<workspace UUID>" } of { "cardIds": ["<card UUID>"] }. Een kaart-ID-scope accepteert 1–2.000 UUID's. Deze POST is gelezen zonder bijwerkingen.

Het antwoord bevat compacte kaartsamenvattingen, randen, bord/lijst/label/personen-zoekopdrachten, aangepaste velden op de kaart, en truncated. Elke kaart voegt toe inScope en zijn canoniek url. Elk bord bevat canEdit voor de bewerkingsbevoegdheid van de beller. EEN blocks rand loopt van sourceCardId (de voorwaarde) om targetCardId (de afhankelijke); relates_to is symmetrisch.

De wandeling begint bij open, niet-gearchiveerde bereikkaarten met relaties, volgt blokkeerranden in beide richtingen over leesbare borden en stopt bij voltooide kaarten. Gerelateerde buren zijn één hop uit de zaden inbegrepen. Ontoegankelijke kaarten worden weggelaten; blockedByCount telt nog steeds hun actieve blokkers. De grafiek stopt bij 400 kaarten en sets truncated: true; verklein de reikwijdte wanneer een volledige keten nodig is. Inloggegevens voor de werkruimte blijven binnen hun werkruimte.

Zie Afhankelijkheden bekijken voor hoe de app deze gegevens presenteert en bewerkt. MCP retourneert een uitgebreide agentgeoriënteerde projectie in plaats van deze compacte samenvattingen.

Bord- en werkruimtemodel

De API van Kanera vertegenwoordigt beide gebruikersgerichte modellen:

• Een standaardwerkruimte bevat meerdere borden.
• Er wordt een zelfstandig bord meegeleverd kind: "board" door eindpunten die de ondersteunende container blootleggen, maar gebruikers ervaren het als één onafhankelijk bord.
• Borden bevatten kaarten.
• Lijsten, labels en aangepaste velden horen alleen bij een zelfstandig bord of worden gedeeld op elk bord in een standaardwerkruimte.
• Toewijzingseindpunten kunnen kaarten retourneren die aan verschillende borden in de werkruimte zijn toegewezen.
• Privéborden zijn alleen zichtbaar waar de API-sleutel toegang heeft.
• Een persoonlijke sleutel kan borden zien in werkruimten waar de eigenaar toegang toe heeft.
• Een werkruimtesleutel kan alleen borden binnen zijn ene werkruimte zien.

Dit is belangrijk bij het bouwen van integraties. Gebruik een zelfstandig bord als het schema onafhankelijk moet blijven. Gebruik in een werkruimte bestaande lijsten en velden opnieuw, zodat rapportage, toewijzingsquery's en aggregatie van aangepaste velden consistent blijven. De Global Work UI kan elk bord bestrijken waartoe de ingelogde persoon toegang heeft, terwijl een werkruimte API-sleutel beperkt blijft tot zijn ene werkruimte.

Paginering en fouten

Maak een lijst van eindpunten die het gebruik van paginering ondersteunen:

Parameter	Betekenis
limit	Aantal records dat moet worden geretourneerd.
before	Cursorstijlfilter voor records vóór een tijdstempel.

Fouten retourneren JSON met:

Veld	Betekenis
code	Stabiele foutcode.
message	Voor mensen leesbare foutmelding.
issues	Optionele validatiedetails.

Gebruik de HTTP-statuscode en de foutcode samen wanneer u besluit of u het opnieuw wilt proberen, de invoer wilt corrigeren of een beheerder wilt vragen de toegang bij te werken.

Webhaken

Webhooks laten externe systemen reageren wanneer werk verandert in Kanera. Zie Webhaken voor installatie, leveringsverificatie en de volledige lijst met ondersteunde webhookgebeurtenistypen.

Als het doel is om kaartactiviteit in een teamchatkanaal te plaatsen, hoef je niets te bouwen: gebruik Chatbestemmingen voor Slack, Discord, Telegram of Zulip.

Externe links

Met externe koppelingen kunnen integraties duurzame toewijzingen opslaan tussen Kanera-records en records in een ander systeem.

Gebruik externe links als u synchronisatietaken nodig hebt om idempotent te zijn. Een Trello-synchronisatie kan bijvoorbeeld onthouden welke Kanera-kaart is toegewezen aan welke Trello-kaart zonder verborgen integratie-metagegevens in de kaartbeschrijving te plaatsen.

Beveiligingsaanbevelingen

• Gebruik één API-sleutel per integratie.
• Gebruik het laagste bereik dat werkt.
• Bewaar sleutels en webhookgeheimen in een geheimmanager.
• Roteer sleutels en webhookgeheimen wanneer mensen weggaan of systemen veranderen.
• Plaats geen API-sleutels in Scratchpad, Notities, kaarten, opmerkingen, bronbeheer, logs of schermafbeeldingen.
• Controleer de webhookhandtekeningen voordat u payloads verwerkt.
• Maak webhook-handlers idempotent omdat leveringen opnieuw kunnen worden geprobeerd.
• Registreer voldoende aanvraag- en gebeurtenis-ID's om fouten in het synchronisatiegedrag op te sporen zonder dat er geheimen moeten worden vastgelegd.

Gerelateerde pagina's

• Kanera CLI
• Typescript SDK
• Verbind Kanera met uw AI-agent
• Sluit een AI-agent aan
• Automatiseringen
• Mondiaal werk
• Aangepaste velden