Kanera API

Kanera's offentlig API lar deg bygge integrasjoner rundt det samme arbeidet teamet ditt administrerer i appen: arbeidsområder, tavler, kort, lister, skilletegn, kommentarer, sjekklister, notater, vedlegg, etiketter, egendefinerte felt, oppgaver, rangert opp neste køer, aktivitet og eksterne koblinger.

Bruk API-en når Kanera må koble til et annet system, drive en intern arbeidsflyt, overføre data, bygge rapporter eller la et annet verktøy opprette og oppdatere Kanera-arbeid.

Hva du kan bygge

Vanlige API-brukstilfeller inkluderer:

Synkroniser Kanera-kort med en annen arbeidssporer.
Opprett kort fra skjemaer, støttebilletter, chat-meldinger eller CRM-poster.
Bygg egendefinerte rapporteringsdashboards fra tavler, oppgaver, etiketter, egendefinerte felt og aktivitet.
Importer arbeid til Kanera fra et annet system.
Hold eksterne poster knyttet til Kanera-kort eller notater.
Legg til kommentarer eller statusoppdateringer fra et annet verktøy.
Last opp og legg ved filer på kort eller notater.
Les aktivitetshistorikk for revisjon, rapportering eller automatisering.

Kanera-integrasjoner kan målrette mot frittstående tavler eller arbeidsområder. Et frittstående tavle har egne lister, etiketter og egendefinerte felt. Et arbeidsområde deler disse ressursene på tvers av tavlene, noe som gjør rapportering og synkronisering av arbeidsflyter enklere å holde konsekvent.

Offisielle kunder

Du trenger ikke å starte fra curl. To førstepartsklienter pakker samme API:

Kunde	Installasjon	Bruk den til
Kanera CLI	`npm install --global @kanera/cli`	Terminalbruk, skallskript og AI-agenter som kan kjøre kommandoer.
TypeScript SDK	`npm install @kanera/sdk`	TypeScript og JavaScript integrasjoner. Ingen runtime avhengigheter; kjører på Node, Bun, Deno, arbeidere og nettlesere.

SDK-en er MIT-lisensiert, så det å legge den inn i ditt eget program reiser ingen spørsmål om lisenspolicy. Bruk REST-endepunktene direkte for et annet språk.

API-referanse

Kanera REST API er på:

https://api.kanera.app

Detaljert referanse på endepunktnivå er tilgjengelig på:

https://api.kanera.app/docs

Den offentlige API-tjenesten inneholder referansen på endepunktnivå:

Sti	Bruk
`/docs`	Interaktiv Scalar API referanse.
`/swagger`	Swagger UI referanse.
`/openapi.json`	OpenAPI-dokument for SDK-generering og verktøy.

For Kanera, åpne:

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

Bruk denne siden som startveiledning, og bruk deretter API-referansen for nøyaktige endepunktbaner, forespørselsobjekter, svarskjemaer og tilgjengelige webhook-hendelsestyper.

Bruk endepunktreferansen

Åpne Skalar for referansen for det primære endepunktet. Hver operasjon viser metoden og banen, det nødvendige omfanget, banen og spørringsparametrene, forespørselsskjemaet, svarskjemaet og feilsvarene. Bruk Godkjenn å gi en bærer token når du vil prøve en forespørsel.

Bruk Swagger UI når verktøy eller arbeidsflyt er bygget rundt Swagger . Last ned OpenAPI JSON for SDK-generering, forespørselsvalidering eller importering av API-en til en annen klient.

OpenAPI-dokumentet er kilden til sannheten. Kopier et eksempel fra referansen i stedet for å gjette en forespørselskropp, og test skrive- eller sletteoperasjoner mot det tiltenkte arbeidsområdet før du automatiserer dem.

Sluttpunktgrupper

Gruppe	Typiske operasjoner
Arbeidsområder og tavler	Oppdag tilgjengelig arbeid, åpne fullstendig styrestatus, administrer medlemmer og gjester, og opprett eller omorganiser tavlene.
Lister, skilletegn og kort	Opprett, oppdater, posisjoner, flytt, fullfør, arkiver, dupliser og rediger massearbeid.
Notater og vedlegg	Opprett nestede notater, administrer låser og tilbakekoblinger, last opp filer direkte eller gjennom en engangsopplastingskobling, og les et vedleggs byte.
Kladd	Les innringerens private sider i Scratchpad og ta opp raske oppgaver til en innboksside.
Felter og etiketter	Administrer egendefinerte felt, alternativer og gjenbrukbare kortetiketter på arbeidsområdenivå.
Kommentarer og aktivitet	Les kortfeeder, skriv kommentarer og reaksjoner, og gjennomgå styrets aktivitet.
Neste prioriteringer	Oppdag lesbare køer, liste lag rekkefølge, og legge til, flytte eller fjerne rangerte kort.
Følger	Se eller slutt å se på kort og tavler, angi, fjerne eller oppgi påminnelser om private kort, og avspør innboksen for varsling.
Agent kjører	Annonser at en agent jobber med et kort, hjerteslag mens det kjører, og ta opp hvordan det endte.
Søk og eksterne lenker	Søk etter tilgjengelig innhold og vedlikehold idempotente mappinger til poster i andre systemer.
Webhooks	Registrer og administrer endepunkter, inspiser eller prøv leveranser på nytt, og motta signerte endringshendelser uten å avgi en avstemning.

Velg en API-nøkkeltype

Kanera har to API-nøkkeltyper. De autentiserer på samme måte, men tilgangsmodellen er forskjellig.

Nøkkeltype	Lag det fra	Bruk den når	Tilgangsmodell
Personlig API-nøkkel	Profilinnstillinger -> API-nøkler	Du kobler til ditt eget skript, CLI eller MCP-klient og vil at den skal fungere på tvers av tavlene du kan få personlig tilgang til.	Fungerer som deg, på tvers av alle arbeidsområder og tavle du kan få tilgang til, og respekterer din rolle på hver tavle. Les eller Skriv scope caps hva den kan gjøre innenfor den tilgangen. Den kan ikke utføre arbeidsområde-admin handlinger.
Arbeidsområde eller API-nøkkel for tavle	Arbeidsområdeinnstillinger -> API eller Innstillinger for -> API	Du konfigurerer en teamintegrasjon, tjenestekonto, webhook-produsent, synkroniseringsjobb eller automatisering for ett arbeidsområde eller frittstående tavle.	Omfattet til det arbeidsområdet eller det frittstående tavlen. Les, Skriv, eller Administrator Det er viktig å kontrollere hva integreringen kan gjøre.

Bruk en personlig nøkkel for brukereide arbeidsflyter. Bruk et arbeidsområde eller en brettnøkkel for delt integrasjon eller produksjonsintegrasjoner som skal eies, roteres og revideres med destinasjonen.

Plankrav

Personlige API-nøkler og interaktive AI-agenttilkoblinger fungerer på Alle planer, inkludert vert Free. De fungerer som en nåværende bruker, slik at de når nøyaktig de tavlene som brukeren kan åpne, i Free og Pro organisasjoner likt.

API-nøkler for arbeidsområde og tavle, uovervåkede OAuth-serviceagenter, webhooks og chat-destinasjoner trenger Pro eller 30-dagers Pro-rettssaken. De kjører på vegne av organisasjonen uten at noen er logget på, så de er ikke tilgjengelige på verts Free, der arbeidsområdets innstillingsside forklarer dette i stedet for å vise opprettelsesskjemaet. 403 med feilkoden PLAN_LIMIT, så en integrasjon kan fortelle et planproblem bortsett fra et tillatelsesproblem.

Opprette arbeidsområde eller tavle API-nøkler, OAuth-klienter og chatmål behov arbeidsområde admin tillatelse. Administratorer administrerer også alle webhook-endepunkter i et arbeidsområde. En API-legitimasjonsagent som kan skrive eller en interaktiv OAuth-agent kan registrere endepunkter som er koblet til sin egen tilkobling når brukeren er et arbeidsområdemedlem. Personlige API-nøkler trenger ingen arbeidsområderolle for å bli opprettet.

Når en vertsbasert organisasjon flytter til Free, tilbakekaller Kanera sine aktive arbeidsområde- og tavle-API-nøkler, som også deaktiverer OAuth-tjenesteagentene som er bygget på dem, og /api/v1 Avviser dem på forespørsel, så en nøkkel som overlever andre steder kan fortsatt ikke brukes. Personlige API-nøkler og interaktive agentforbindelser fortsetter å fungere. Webhook-endepunkter og chatmål blir pauset av samme nedgradering. Oppgradering tilbake til Pro gjenoppretter nøklene og endepunktene som nedgraderingen berørte.

Takstgrenser

Forespørsler fra API-nøkler og AI-agenter, over REST og MCP, er begrenset per bruker, på plangrensene til organisasjonen som eier tavlen som blir åpnet:

Styrets organisasjon	Per sekund	Per minutt
Vertskap Free	5	60
Pro eller Pro-prøveversjon	20	400
Selvbetjent	20	400 (konfigurerbar)

En bruker som tilhører både en Free- og en Pro-organisasjon får hver organisasjons grenser på sine egne tavler. Forespørsler over grensen blir ikke avvist med en gang: opptil 10 ventetid i en kø, maksimalt 10 sekunder, og serveres som kapasitetsfri. Kun forespørsler utover den køen mottar 429 med a Retry-After CLI, SDK og MCP-serveren går tilbake og prøver automatisk på nytt.

Selvbetjente operatører kan endre grensene med PUBLIC_API_KEY_RATE_LIMIT_PER_SECOND, PUBLIC_API_KEY_RATE_LIMIT_PER_MINUTE, PUBLIC_API_RATE_LIMIT_QUEUE_SIZE, og PUBLIC_API_RATE_LIMIT_QUEUE_MAX_WAIT_MS. Se Webhooks for den fullstendige nedgradering av atferd.

Opprett en personlig API-nøkkel

Åpne Profilinnstillinger.
Gå til API-nøkler tab.
Opprett en personlig API-nøkkel.
Velg Skrivebeskyttet eller Les og skriv.
Legg til en valgfri privat etikett slik at du kan gjenkjenne hvor nøkkelen brukes.
Kopier hemmeligheten når den vises.

Personlige nøkler er alltid knyttet til brukeren som opprettet dem. De følger eierens virkelige bretttilgang og rolle, og aktivitet vises som eieren. Det er ikke noe adminomfang: en personlig nøkkel kan aldri utføre arbeidsområdeadministrasjon, uansett eierens rolle.

Skrivbare personlige nøkler

En personlig nøkkel er lese og skrive med mindre du velger noe annet, som er hva en eksisterende nøkkel eller en uendret opprette flyt gir deg.

Velg Skrivebeskyttet når legitimasjonen går et sted du ikke vil se: en AI-agent, en rapporteringsjobb, en CI-sjekk, et dashbord. En skrivebeskyttet nøkkel kan liste, lese, søke og rapportere, og Kanera nekter hver mutasjon med 403 og feilkoden FORBIDDEN. Fordi avslaget skjer på API i stedet for i klienten, kan en feiloppførsel eller hurtiginjisert agent fortsatt ikke endre arbeidet ditt.

Omfanget er fast når nøkkelen er opprettet. For å endre det, opprett en ny nøkkel og tilbakekall den gamle.

Hemmeligheten vises én gang. Lagre den i din lokale hemmelige leder, MCP- klientkonfigurasjon eller miljøvariabler.

Opprette en arbeidsområde- eller tavle-API-nøkkel

Åpne arbeidsområdet eller det frittstående tavlen.
Gå til Arbeidsområdeinnstillinger -> API eller Innstillinger for -> API.
Opprett en API-nøkkel for arbeidsområdet.
Velg det minste omfanget som passer integrasjonen.
Kopier hemmeligheten når den vises.

API-nøkler for arbeidsområde er arbeidsområde. En nøkkel kan bare få tilgang til ressurser i arbeidsområdet der den ble opprettet, og hvor skaperen fortsatt har tilgang.

Hemmeligheten vises en gang. Lagre den i integrasjonens hemmelige manager eller miljøvariabler.

Arbeidsområde API nøkkelomfang

Virkeområde	Bruk den når
Les	Integrasjonen trenger bare å lese, søke, rapportere eller eksportere Kanera-data.
Skriv	Integrasjonen må opprette eller oppdatere arbeid, for eksempel kort, kommentarer, etiketter, oppdragsgivere, egendefinerte feltverdier, notater eller vedlegg.
Administrator	Integrasjonen trenger offentlig API-drift på admin-nivå der det støttes. Bruk dette sparsomt.

Les, Skriv, og Administrator gjelder for arbeidsområde og bretttaster. Personlige nøkler velge mellom Les og Skriv bare, og alltid arve eierens styrenivå tillatelser på toppen av det.

Bruk separate API-nøkler for separate integrasjoner. Dette gjør tilgangen enklere å tilbakekalle, rotere og revidere. For delte systemer, foretrekker arbeidsområdenøkler slik at tilgangen ikke er knyttet til en persons personlige verktøy.

Autentisering

Send API-nøkkelen som et tegn for bærer:

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

Kanera API-taster bruker prefikser for miljøet:

Prefiks	Miljø
`kanera_live_...`	Produksjon
`kanera_stg_...`	Opptak
`kanera_dev_...`	Utvikling
`kanera_test_...`	Test

Personlige nøkler bære en u marker etter selger prefiks, så kanera_u_live_... Det er en personlig nøkkel og kanera_live_... er en arbeidsområde eller brettnøkkel. Begge godkjenner på samme måte.

Manglende eller ugyldige nøkler returneres 401. Gyldige nøkler uten tillatelse for en ressurs eller operasjon retur 403 — også ved forsøk på å skrive med en nøkkel som bare har lesetilgang.

OAuth for AI-agenter

Kanera støtter OAuth 2.0 slik at en kompatibel AI-agent kan koble til Kanera MCP gjennom nettlesersamtykke eller en tjenestetilkobling i stedet for å lagre en API-nøkkel.

En OAuth-tilkobling er for MCP; det er ikke en generell offentlig API-legitimasjon. Bruk en personlig, arbeidsområde eller tavle-API-nøkkel når din egen integrasjon må ringe /api/v1 direkte.

Det er tre OAuth-stier:

Interaktive agenter bruke autorisasjonskodeflyten med PKCE. En person godkjenner tilkoblingen en gang i nettleseren, og agenten fungerer som den brukeren. Dette er hvordan kompatible MCP-klienter som Claude, ChatGPT, Copilot og Codex kobler seg uten en API-nøkkel.
Enhetsklienter bruk enhetsautorisasjonsbevilgningen (urn:ietf:params:oauth:grant-type:device_code). Klienten viser en kort kode, en person godkjenner den i en nettleser på hvilken som helst enhet, og klienten poller for tokens. Bruk dette for en CLI eller hodeløs klient som ikke kan motta en nettleseromdirigering. Se referanse for enhetsautorisasjon.
Ubetjente agenter Bruk av client_credentials Du oppretter en klient-ID og hemmelighet i Arbeidsområdeinnstillinger -> API og utveksle dem for kortvarige tokens, uten nettlesertrinn. Bruk disse for CI, cron eller server-side agenter.

Se Koble til en AI-agent for oppsett, omfang og tilkoblingsadministrasjon. Egendefinerte OAuth-klientforfattere kan finne protokolldetaljene i MCP teknisk referanse.

Base URL og versjonsstyring

REST endepunkter lever under /api/v1 på den offentlige API-tjenesten.

For eksempel:

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

Operativ hjelp som /docs, /swagger, /openapi.json, signerte medie-URLer og webhook-hendelses-oppdagelse kan være utenfor /api/v1 prefiks. Behandle signerte medieadresser som returneres av API som ugjennomsiktige nettadresser og bruk dem som angitt.

Første forespørsler

Sjekk hvem som er legitimasjon. GET /api/v1/session returnerer brukeren, organisasjonen, legitimasjonstypen og scope (read betyr at hver endring blir avslått), pluss brukerens timeZone og today, den gjeldende datoen i den sonen, slik at en klient kan løse "i dag" eller "i morgen" måten Kanera stempler forfallsdatoer:

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

Liste over arbeidsområder API-nøkkelen har tilgang til:

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

Deretter lister du opp tavler i et arbeidsområde:

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

Åpne en tavle for å få tavlen, arbeidsområdelister, brettseparatorer, synlige kort, medlemmer, etiketter og egendefinerte felt som trengs for å gjengi eller synkronisere arbeid:

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

Opprett et kort:

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

En skaper kan også sette labelIds, assigneeIds, dueDateLocalDate (YYYY-MM-DD), og dueDateSlot i samme skrive, slik at kortet kommer fullt beskrevet og dens etikett automatiseringer kjøre en gang.

Lag flere kort samtidig, opptil 50 per forespørsel på ett tavle. Hvert kort navngir sin egen liste og lander nederst på den i forespørselsrekkefølge:

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

Hvert kort kontrolleres før noe opprettes, så en ukjent liste, etikett eller oppdragsgiver avviser hele forespørselen med en 400 Dette er navnet på en slik innførsel som cards[1]: one or more label ids are invalidHvert kort utløser deretter de samme automatiseringene, varslinger og webhooks som et enkelt opprette.

Kortsvar inkluderer det uforanderlige workspaceId, ugjennomsiktig organisationKey, positiv number, nåværende menneskelig lesbar key som PROJ-123, og ren nettleser url. Et arbeidsområde prefiks kan endres, men kortnummeret ikke.

Løs en gjeldende eller historisk kortnøkkel før du ringer et id-basert mutasjonsendepunkt:

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

Oppløsningen er ikke sensitiv for store og små bokstaver og returnerer kortets nåværende id, arbeidsområde, tavle, liste, nummer, nøkkel og nettleser-URL. Organisasjonsnøkkelen er den ugjennomsiktige verdien som returneres av Kanera, ikke et organisasjonsnavn eller en slug. Manglende og utilgjengelige kort returnerer begge 404.

Oppdater et kort:

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

Legg til en kommentar

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

Erstatt kortets etiketter eller oppdragsgivere med et nøyaktig sett:

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

Disse to PUT operasjoner erstatter hele settet. Send en tom matrise for å fjerne den. Bruk de dokumenterte massetilføyings- og -fjerningsoperasjonene når du trenger oppdateringssemitikk på tvers av valgte kort.

Fullfør et kort:

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

Administrer skilletegn på tavle

En skilletegn er et bretteid, tittel, eventuelt farget element i en arbeidsflytlistes blandede kort-og-separator bestillingsfelt. Opprett en på et nøyaktig skrevet 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\"}}"

Oppdater tittelen eller fargen med PATCH /api/v1/separators/{id}Flytt den med POST /api/v1/separators/{id}/moveog slette det med DELETE /api/v1/separators/{id}. Flytt organer navn destinasjonen listId og leverer nøyaktig en beforeItem eller afterItem; elementet kan være en { "type": "card", "id": "..." } eller { "type": "separator", "id": "..." } referanse. A null afterItem Det betyr toppen og en null beforeItem Sletting av en separator etterlater kortene uendret.

Administrer neste ordre

API-en viser de samme rangerte køene som brukes av Hjem-, Mine kort- og Lagkort:

Sluttpunkt	Bruk
`GET /api/v1/work/priority-targets`	Liste over brukere som kan lese i køene på legitimasjonsinformasjonen.
`GET /api/v1/work/priorities`	Les alle tillatte køer i ett svar.
`GET /api/v1/work/priorities/{userId}`	Les en kø i rangrekkefølge.
`POST /api/v1/work/priorities/{userId}/cards`	Legg til et tildelt aktivt kort i en forankret posisjon.
`POST /api/v1/card-priorities/{id}/move`	Flytt én køoppføring før eller etter en annen synlig oppføring.
`DELETE /api/v1/card-priorities/{id}`	Fjerne kortet uten å endre det.

Personlig legitimasjon kan alltid lese sin egen kø. Å lese en annen persons kø krever effektiv administratorautoritet i et delt arbeidsområde, og skriver også krever en skrivekompatible legitimasjon pluss autoritet for målkortet. Bruk oppføringsidene som returneres av køen som flytteankere; rangeringer er presentasjonsverdier, ikke mutasjons-id.

Legg ved og les filer

POST /api/v1/cards/{id}/attachments tar en flerdelt opplasting. Når filen bor et sted som innringeren ikke kan streame direkte fra, for eksempel en AI-agents sandkasse, mynt en engangsopplastingskobling i stedet og PUT De rå bytene til det:

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"

Koblingen fungerer én gang, utløper etter 15 minutter, og slutter å fungere hvis nøkkelen som opprettet den, blir tilbakekalt.
Kanera lagrer filen under navnet og typen som ble registrert da koblingen ble opprettet, og utleder typen fra utvidelsen når du utelater mimeType. Loggfiler (.log, .out, .jsonl, og lignende) lagres som ren tekst.
Opprette en kobling trenger en skrive-stand legitimasjon og Editor tilgang til kortet. Lagringsgrenser er merket både når koblingen er opprettet og når filen kommer.
Opplastingssvaret er det nye vedlegget, og alle som ser på kortet, ser det umiddelbart.

Lese vedleggets byte med GET /api/v1/cards/{id}/attachments/{attachmentId}/content. Den støtter Range forespørsler, og ?variant=cover (opptil 1200px) eller ?variant=thumbnail (400px) returnerer JPEG-kopiene Kanera lager av PNG-, JPEG-, GIF- og WebP-bilder.

Fange til Scratchpad

POST /api/v1/scratchpad/capture legger til en åpen oppgave i innringerens private KladdPå første side med tittelen pageTitle (standard Inbox), og oppretter siden når den mangler:

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 Hver side med innhold, og PATCH /api/v1/scratchpad/notes/{id} erstatter en side. updatedAt Du leser som baseUpdatedAt å motta 409 SCRATCHPAD_STALE i stedet for å overskrive endringer gjort siden. Scratchpad tilhører en person, så arbeidsområde API-nøkler motta 403; bruke en personlig nøkkel eller en OAuth-tilkobling.

Se kort og angi påminnelser

Den Følger endepunkter administrerer innringerens egne abonnementer, slik at arbeidsområde API-nøkler mottar 403; bruk en personlig nøkkel eller en OAuth-tilkobling. Endring av dem trenger en skrivekompatible legitimasjon, men bare lesetilgang til kortet.

Sluttpunkt	Bruk
`GET /api/v1/cards/{id}/follow`	Se på kortet og din påminnelse på det.
`PUT` / `DELETE /api/v1/cards/{id}/watch`	Se eller slutte å se på et kort. Returnerer samme tilstand som `follow`.
`PUT` / `DELETE /api/v1/boards/{id}/watch`	Se eller slutte å se på en tavle.
`PUT /api/v1/cards/{id}/reminder`	Angi påminnelsen din: `{"remindAt": "2026-10-16T15:00:00+01:00"}`.
`DELETE /api/v1/cards/{id}/reminder`	Klargjør påminnelsen.
`GET /api/v1/reminders`	Dine ventende påminnelser, soonest først. `?status=all` Det gjelder også de som allerede har fått sparken.
`GET /api/v1/notifications`	Avstemning innboksen fremover fra en markør. Se nedenfor.

remindAt er et ISO-øyeblikk med en offset, i fremtiden og maksimalt 56 dager (åtte uker) fremover. Du holder en påminnelse per kort, så innstillingen erstatter og armerer den igjen. De andre åpne øktene oppdateres umiddelbart. Verken se eller påminnelser vises i kortets aktivitet. Se Påminnelser.

GET /api/v1/notifications er for et skript eller agent som ikke kan motta webhooks, for eksempel en som kjører på en bærbar datamaskin. Det returnerer de samme radene som varslingsskuffen (svar, nevner, tildelinger og endringer på kort du ser på eller er tildelt), eldste først. Ring det en gang uten since for de siste radene, og deretter sende hvert svar cursor tilbake som sinceGjenta mens hasMore er true, for å få bare det som er nytt. Hver rad bærer en en-linje summary, den card nøkkel og URL, den actor, og a commentExcerpt for kommentarer. Rader vises noen sekunder etter hendelsen. En AI agent tilkobling ser ikke varsler sine egne skriver forårsaket med mindre du legger til includeSelf=trueOg polling markerer aldri noe som leses.

Spore en agents arbeid under flyvning

Når den som ringer er en AI-agent i stedet for en synkroniseringsjobb, kan den kunngjøre arbeidet den gjør på et kort. Kanera viser deretter en levende chip på kortflisen, viser kjøringen i kortdetaljer og registrerer kortaktivitetsrader for start og slutt - slik at en person kan se at noe skjer og hvem gjør det, uten å vente på resultatet.

Sluttpunkt	Bruk
`POST /api/v1/cards/{cardId}/agent-runs`	Start et løp. Kroppen tar `title` (påkrevd), `summary`, og `externalUrl`.
`GET /api/v1/cards/{cardId}/agent-runs`	Liste et kort kjører. Live bare som standard; pass `includeEnded=true` Historien først, den nyeste.
`GET /api/v1/agent-runs/{id}`	Les et løp.
`PATCH /api/v1/agent-runs/{id}`	Oppdater, hjerteslag eller fullfør et løp. Hvert felt er valgfritt, så `{}` Det er bare hjerteslag.

Start løpet, og hold id Fra svaret:

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

Deretter rapporterer du fremgangen og avslutter den:

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

Status er running, blocked, succeeded, failed, cancelled, og stalled:

running og blocked er de to levende stater. Bruk blocked mens agenten venter på en person, for eksempel et spørsmål eller en godkjenning; kortets chip blir gul.
succeeded, failed, og cancelled terminal. En terminalstatus avslutter kjøringen og gjør den uforanderlig, så enhver senere PATCH returer 409 med message: agent run has already ended.
stalled er satt av Kanera, ikke av deg, når en live run slutter å pulsere i femten minutter, så en krasjet agent kan ikke forlate et kort som viser "arbeider" på ubestemt tid. En stoppet løp er ikke avsluttet: agenten kan fortsatt lukke den med en terminalstatus, eller angi running å gjenoppta.

Hver PATCH oppdaterer hjerterytmen, inkludert en som endrer ingenting, så send en keep-alive godt inne i femten minutters vinduet på en lang jobb. Redaktør tilgang og en skrive-kompatible legitimasjon, akkurat som alle andre kort skrive. Kjører også avgir agentRun:started og agentRun:updated webhook hendelser.

En agent som er koblet gjennom OAuth er registrert som agenten som handler for brukeren: dens løp, kommentarer og aktivitetsrader bærer agentens navn, og personen den handler for blir varslet om hva den gjorde. En personlig API-nøkkel som brukes av ditt eget skript, fungerer fortsatt som eier.

Registrer en webhook fra en integrasjon

Arbeidsområdeadministratorer kan administrere alle generiske webhook-endepunkter. En API-legitimasjonsagent som ikke er administrator, eller en interaktiv OAuth-agent kan også opprette en når brukeren tilhører arbeidsområdet. Kanera markerer det endepunktet scope: "connection", og bare de samme tilkoblings- og arbeidsområdeadministratorene kan liste eller administrere det. Dette lar en agent abonnere på bordhendelser uten å motta arbeidsområde-administratorautoritet.

Bruk POST /api/v1/workspaces/{workspaceId}/webhooks for å opprette endepunktet og lagre engangs secret fra svaret. Den samme ressursen eksponerer liste, oppdatere, slette, hemmelig rotasjon, leveringshistorikk og mislykkede leveringsforsøk. Se Webhooks for endepunktskartet og signaturreglene.

En pålitelig integrasjonsflyt

Ring GET /api/v1/workspaces eller GET /api/v1/boards å oppdage bare ressurser legitimasjonen kan få tilgang til.
Bruk POST /api/v1/boards/{id}/open når du trenger tavlen pluss lister, kort, medlemmer, etiketter og egendefinerte felt i ett svar.
Lagre returnerte id-er for API-mutasjoner. Navn kan redigeres. En leselig kortnøkkel kan løses til gjeldende kort-id når en person eller ekstern post leverer en.
Valider skrive organer mot operasjonen skjema i Scalar eller OpenAPI.
Behandle 401 som ugyldig autentisering, 403 som utilstrekkelig tilgang eller en planport, 404 som manglende eller utilgjengelige data, 409 som en konflikt mellom staten og 429 Som et signal til å trekke seg tilbake.
Registrer svaret x-request-id i integrasjonslogger uten å logge legitimasjon eller sensitivt innhold.

Kortforhold

Relasjoner kobler kort i samme arbeidsområde, inkludert på tvers av tavlene. direction Leser fra kortet i stien: blocks Dette kortet blokkerer målet. blocked_by Målet blokkerer dette kortet, og relates_to Ingen nødvendig ordre.

Metode og sti	Formål
`GET /api/v1/cards/{cardId}/relations`	Les mer om synlige relasjoner og `hiddenBlockerCount`.
`POST /api/v1/cards/{cardId}/relations`	Legg til `{ "targetCardId": "<UUID>", "direction": "blocked_by" }`.
`DELETE /api/v1/cards/{cardId}/relations/{relationId}`	Fjerne en relasjon ved hjelp av ID-en.

Kortet inneholder relations og hiddenBlockerCount; kort sammendrag avsløre blockedByCount. Et aktivt kort er blokkert mens minst en forutsetning er ufullstendig og ikke arkivert. Bruk filters: { blockedOnly: true } med POST /api/v1/work/cards/query å returnere kun blokkerte åpne kort, eller atRiskOnly: true for åpne kort hvis synlige blokkering er forsinket eller forfaller etter dem. POST /api/v1/work/portfolio/query returer blocked og atRisk Antall per tavle og totalsum.

Legge til en eksisterende forhold er idempotent. Selvkoblinger, kryss-arbeidsplass linker, avhengighetssykluser, og et fullført kort som en ny blokkering er avvist. Skriver krever redigeringstilgang til banen kortet og uansett kort blir blokkert, pluss lese tilgang til det andre kortet. Utilgjengelige relasjoner er utelatt fra leser; deres aktive blokkeringer bidrar bare til hiddenBlockerCount.

Å rydde den siste aktive blokkeringen kan kjøre automatiseringer og sende overleveringsvarsler. Å åpne eller gjenopprette en blokkering kan blokkere kortet igjen. Fullføring gjennom API er fortsatt tilgjengelig uten webappens interaktive advarsel. Se Kortrelasjoner og blokkering for livssyklusadferd.

Avhengighetsgrafer

POST /api/v1/cards/dependency-graph leser grafen bak avhengighetsvisningen. Passer nøyaktig ett omfang:

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

Alternativt passerer { "workspaceId": "<workspace UUID>" } eller { "cardIds": ["<card UUID>"] }. Et kort-ID-omfang godtar 1–2 000 UUID-er. Denne POST-forespørselen leser data uten bivirkninger.

Svaret inneholder kompakte kortsammendrag, kanter, oppslagstavler/lister/etiketter, egendefinerte felt for kort og truncated. Hvert kort legger inScope Den kanoniske url. hver tavle inkluderer canEdit for den som ringer, er avhengighetsredigeringsmyndighet. A blocks edge løper fra sourceCardId (Forutsetning) targetCardId (avhengig av) relates_to Det er symmetrisk.

Turen starter fra åpne, uarkiverte scope kort med relasjoner, følger blokkere kanter begge veier over lesbare tavle, og stopper ved ferdige kort. Relaterte naboer er inkludert ett hopp fra frøene. Utilgjengelige kort er utelatt; blockedByCount fortsatt teller sine aktive blokkere. Grafen stopper på 400 kort og sett truncated: true; begrense omfanget når en full kjede er nødvendig. Arbeidsområde legitimasjon forblir inne i arbeidsområdet.

Se Avhengigheter Vis MCP returnerer en utvidet agentorientert projeksjon i stedet for disse kompakte sammendragene.

tavle og arbeidsplass modell

Kanera's API representerer begge brukerrettede modeller:

Et standard arbeidsområde inneholder flere tavler.
En frittstående tavle returneres med kind: "board" av endepunkter som eksponerer støttebeholderen, men brukerne opplever den som ett uavhengig tavle.
tavle inneholder kort.
Lister, etiketter og egendefinerte felt tilhører bare et frittstående tavle eller deles på tvers av alle tavle i et standard arbeidsområde.
Tildelingsendepunkter kan returnere kort som er tildelt på tvers av kortene i arbeidsområdet.
Private boards er bare synlige der API-nøkkelen har tilgang.
En personlig nøkkel kan se tavler på tvers av arbeidsområder der eieren har tilgang.
En arbeidsområdenøkkel kan bare se tavler i ett arbeidsområde.

Dette er viktig når du bygger integrasjoner. Bruk et frittstående tavle når skjemaet skal være uavhengig. I et arbeidsområde kan du gjenbruke eksisterende lister og felt, slik at rapportering, oppgavespørringer og egendefinert feltaggregering forblir konsistente. Global Work-grensesnittet kan spenne over hver tavle den påloggede personen kan få tilgang til, mens en API-nøkkel for arbeidsområde forblir omfattet av sitt ett arbeidsområde.

Paginasjon og feil

Liste endepunkter som støtter paginering bruk:

Parameter	Betydning
`limit`	Antall poster som skal returneres.
`before`	Markør-stil filter for poster før et tidsstempel.

Feil returnerer JSON med:

Felt	Betydning
`code`	Stabil feilkode.
`message`	Menneskelesbar feilmelding.
`issues`	Valgfrie valideringsdetaljer.

Bruk HTTP-statuskoden og feilkoden sammen når du bestemmer deg for å prøve på nytt, rette inndata eller be en administrator om å oppdatere tilgang.

Webhooks

Webhooks lar eksterne systemer reagere når arbeidet endres i Kanera. Se Webhooks for oppsett, leveringsbekreftelse og den fullstendige listen over støttede webhook-hendelsestyper.

Hvis målet er å legge inn kortaktivitet i en gruppechatkanal, trenger du ikke å bygge noe: bruk Chat Destinasjoner for Slack, Discord, Telegram eller Zulip.

Eksterne lenker

Eksterne lenker lar integrasjoner lagre varige mappinger mellom Kanera-poster og poster i et annet system.

Bruk eksterne lenker når du trenger synkroniseringsjobber for å være idempotent. For eksempel kan en Trello sync huske hvilke Kanera-kort som Trello-kort uten å sette skjulte integrasjonsmetadata i kortbeskrivelsen.

Sikkerhetsråd

Bruk en API-nøkkel per integrasjon.
Bruk det laveste omfanget som fungerer.
Lagre nøkler og webhook hemmeligheter i en hemmelig manager.
Roter nøkler og netthook hemmeligheter når folk forlater eller systemer endres.
Ikke legg API-taster i Scratchpad, Notater, kort, kommentarer, kildekontroll, logger eller skjermbilder.
Bekreft webhook-signaturer før du behandler nyttelaster.
Gjør webhook handlers idempotent fordi leveranser kan prøves på nytt.
Logg nok forespørsel og hendelses-IDer til å feilsøke synkroniseringsadferd uten å logge hemmeligheter.

Hva du kan bygge​

Offisielle kunder​

API-referanse​

Bruk endepunktreferansen​

Sluttpunktgrupper​

Velg en API-nøkkeltype​

Plankrav​

Takstgrenser​

Opprett en personlig API-nøkkel​

Skrivbare personlige nøkler​

Opprette en arbeidsområde- eller tavle-API-nøkkel​

Arbeidsområde API nøkkelomfang​

Autentisering​

OAuth for AI-agenter​

Base URL og versjonsstyring​

Første forespørsler​

Administrer skilletegn på tavle​

Administrer neste ordre​

Legg ved og les filer​

Fange til Scratchpad​

Se kort og angi påminnelser​

Spore en agents arbeid under flyvning​

Registrer en webhook fra en integrasjon​

En pålitelig integrasjonsflyt​

Kortforhold​

Avhengighetsgrafer​

tavle og arbeidsplass modell​

Paginasjon og feil​

Webhooks​

Eksterne lenker​

Sikkerhetsråd​

Relaterte sider​