Detta är en maskinöversättning av det engelska originaldokumentet. Vid eventuella avvikelser mellan denna översättning och den engelska originalversionen ska den engelska versionen ha företräde. Läs den engelska originalversionen

Offentligt API

Caiioo innehåller ett REST API som låter dig styra allt programmatiskt: köra agenter, hantera verktyg, schemalägga uppgifter med mera. API:et lever på samma lokala server som driver skrivbordsappen och webbläsarbryggan.

Bas-URL: http://localhost:3847/v1

Autentisering: Två sätt att autentisera, båda styrs av API-brytaren i inställningarna:

För externa konsumenter (skript, integrationer, curl): Ställ in en API-åtkomsttoken i Inställningar > API-åtkomst, använd den sedan som en Bearer-token:

curl -H \"Authorization: Bearer DIN_API_TOKEN\" http://localhost:3847/v1/providers

För den lokala appen (automatiskt): Caiioo-skrivbordsappen, webbläsartillägg och mobilappar autentiserar automatiskt via den befintliga relay-auth-headern (x-relay-auth; HTTP-headers är skiftlägesoberoende). Ingen manuell konfiguration behövs — appen hanterar detta bakom kulisserna. Relay-auth-förfrågningar kringgår brytaren Aktivera offentligt API eftersom de redan är betrodda; endast bearer-token-förfrågningar styrs av brytaren.

Konfiguration:

Öppna Caiioo Inställningar > API-åtkomst
Slå på Aktivera offentligt API
Ställ in en API-åtkomsttoken (valfri sträng du väljer — hantera den som ett lösenord)
Använd den token i alla API-förfrågningar

API:et är tillgängligt på localhost och via det privata reläet. Kontrollera GET /v1/auth/info (ingen autentisering krävs) för aktuell status och konfigurationsinstruktioner.

Hastighetsbegränsningar: varje /v1/*-förfrågan är hastighetsbegränsad per klient-IP — 100 GET-förfrågningar per minut för läsning och 30 skrivförfrågningar per minut (POST / PATCH / DELETE) kombinerat. Förfrågningar över gränsen får 429. Webhook-leveranser (POST /v1/webhooks/:id) är inte bearer-autentiserade och omfattas inte av dessa gränser.

Profiler

En enskild enhet kan innehålla flera användarprofiler (t.ex. privat + arbete). API:et låter externa skript inspektera tillgängliga profiler och byta aktiv profil innan annat arbete utförs. Skapande, uppdatering och radering av profiler exponeras medvetet inte via det publika API:et — dessa flöden hör hemma i appens onboarding-gränssnitt.

Lista profiler:

GET /v1/profiles

Returnerar { profiles: [...] } med en post per icke-raderad profil. Varje post inkluderar id, name, email, avatarUrl, tier, accessibleModes, license, organization, preferences, onboardingComplete, createdAt, lastAccessedAt. Token-bärande fält (serviceCredentials, oauthConnections) och synkroniseringsinterna fält (vectorClock, lastModifiedBy) är borttagna. Använd /v1/connectors för att inspektera OAuth-anslutningar.

Hämta aktiv profil:

GET /v1/profiles/active

Returnerar { profile } för den profil som för närvarande används av denna server. Alla /v1/*-resurser kopplade till en profil (trådar, bilagor, inställningar, färdigheter) körs mot denna.

Byt aktiv profil:

PUT /v1/profiles/active
Content-Type: application/json

{ "profileId": "användar-uuid-från-listan" }

Returnerar { profile } för den nyligen aktiverade profilen. Returnerar 404 om ID:t inte är en känd profil.

Leverantörer & Modeller

Upptäck vilka LLM-leverantörer som är konfigurerade och vilka modeller som är tillgängliga.

Lista leverantörer:

GET /v1/providers

Returnerar varje leverantörstyp som stöds. För närvarande: anthropic, openai, google, openrouter, ollama, poe, mlx, perplexity, baseten, cloudflare. Varje post inkluderar type, displayName, icon, requiresApiKey, hasApiKey, samt ett capabilities-objekt med flaggorna nedan.

Kapabilitetsflagga	Betydelse
`supportsVision`	Leverantören kan ta emot bildindata
`supportsPdfFile`	Leverantören kan ta emot råa PDF-filinnehållsblock nativt
`supportsToolCalling`	Leverantören stöder funktions-/verktygsanrop
`supportsStreaming`	Leverantören strömmar tokens inkrementellt
`supportsExtendedThinking`	Leverantören exponerar en budget för resonemang/tänkande
`supportsPromptCaching`	Leverantören stöder prompt-cache-direktiv
`nativeReasoningBlocks`	Leverantören skickar tänkande som nativa meddelandeblock (kontra text)
`requiresThoughtSignature`	Leverantören kräver att signerade tanke-tokens skickas tillbaka

Kapabilitetsflaggor speglar varje leverantörsklass readonly capabilities-fält (se src/shared/providers/*-provider.ts) och valideras av ett drift-sentinel-test — anropa denna slutpunkt vid körning snarare än att hårdkoda matrisen.

Noteringar för BYOK-leverantörer:

perplexity exponerar en kurerad lista över Sonar-modeller (Perplexity har ingen offentlig /models-slutpunkt).
cloudflare (AI Gateway) är BYOK + multi-leverantör; modellistan bestäms av din gateway-konfiguration och returneras som en tom array av /v1/providers/cloudflare/models. Använd din egen gateway-katalog.

Lista modeller för en leverantör:

GET /v1/providers/openrouter/models

Returnerar modellkatalogen för den leverantören. Varje modell inkluderar id, displayName, och contextLength där det är tillgängligt. Returnerar 503 när leverantören saknar en API-nyckel eller dess uppströmskatalog är oåtkomlig.

Samlad katalog över alla leverantörer:

GET /v1/models

Slår samman modeller från varje konfigurerad leverantör till en lista. Leverantörer utan API-nycklar hoppas över och listas i warnings.

Agenter

Agenter är kärnan i caiioo. Varje agent är ett Läge — en konfigurerad personlighet med sin egen systemprompt, verktyg, variabler och färdigheter.

Lista alla agenter:

GET /v1/agents

Returnerar inbyggda agenter (Shopping, Arbetsplats, Allmänt) och alla anpassade agenter du skapat. Varje är taggad med source: \"builtin\" eller source: \"custom\".

Skapa en anpassad agent:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"min-research-agent\",
  \"branding\": {
    \"name\": \"Research-agent\",
    \"description\": \"Söker på webben och sammanfattar fynd\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Du är en forskningsassistent. Ange alltid källor.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Returnerar 201 med den skapade agenten. En vektorklocka bifogas automatiskt för synkronisering.

Uppdatera en agent:

PATCH /v1/agents/min-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"Research-agent\", \"description\": \"Uppdaterad beskrivning\" } }

Slår samman ändringen med den befintliga agenten och uppdaterar vektorklockan. Inbyggda agenter returnerar 403 — de är skrivskyddade.

Ta bort en agent:

DELETE /v1/agents/min-research-agent

Mjuk borttagning via tombstone (synkroniseras mellan enheter). Returnerar 204.

Köra agenter

Detta är huvudevenemanget — anropa en agent för att bearbeta ett meddelande.

Request body — fält som stöds

Fält	Obligatoriskt	Beskrivning
`agentId`	ja	Inbyggt läges-ID (t.ex. `general`) eller ett anpassat agent-ID
`input.message`	ja	Text för användarmeddelande
`input.attachments`	nej	Array med bilage-ID:n (redan uppladdade via `/v1/attachments`) att bifoga till denna omgång
`input.variables`	nej	Variabelöverskridningar per körning som slås samman i agentens variabelmatchning
`input.tabContext`	nej	Friformssträng som injiceras som sidkontext (används av webbläsarbryggan)
`input.messageId`	nej	Klienttillhandahållet meddelande-ID — användbart för deduplicering vid återförsök
`threadId`	nej	Befintlig tråd att fortsätta. Om den utelämnas skapas och returneras en ny tråd
`mode`	nej	`"sync"` eller `"async"`. Standardvärdet är `"async"`

Synkront läge

Vänta på det fullständiga svaret:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "Vad är det för väder i Paris idag?" },
  "mode": "sync"
}

Returnerar 200 med { content, usage, status: "completed" } efter att agenten är klar. Om agenten stöter på ett fel returneras 500 med { error, status: "error" }. Synkrona körningar gör timeout efter 5 minuter med status: "error" om ingen terminal händelse tas emot — använd async + SSE för allt som kan ta längre tid.

Asynkront läge

Skicka och glöm — användbart för långvariga uppgifter:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Skriv en analys på 2000 ord om trender inom förnybar energi" },
  "mode": "async"
}

Returnerar 202 omedelbart med { runId, threadId, status: "running" }.

Pollning för status:

GET /v1/runs/{runId}

Returnerar { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. Status är en av running, completed, error eller cancelled.

Strömma händelser i realtid (SSE):

GET /v1/runs/{runId}/events

Returnerar en text/event-stream med varje agenthändelse när den inträffar: GENERATION_STARTED, STREAMING_CONTENT, verktygsanrop, underagentsaktivitet och terminalhändelsen (GENERATION_COMPLETE, GENERATION_ERROR eller GENERATION_CANCELLED).

Efter terminalhändelsen skickar servern en sista SSE-ram med event: terminal och en tom datanyttolast som en explicit slut-på-ström-markör, och stänger sedan anslutningen. Klienter bör betrakta mottagandet av den ramen (eller en stängd anslutning) som signalen att sluta läsa.

Om du prenumererar efter att körningen redan har avslutats, spelar servern upp en ram av typen RUN_SNAPSHOT som innehåller den fullständiga slutgiltiga posten (record), följt av event: terminal-markören, och stänger sedan.

Avbryt en körning:

POST /v1/runs/{runId}/cancel

Returnerar { run: { ..., status: "cancelled" } }.

Trådar

Trådar är konversationer. Varje körning av en agent sker inom en tråd, och trådar sparas mellan sessioner. Med API:et kan du lista, läsa, skapa och hantera trådar programmatiskt.

Lista alla trådar (endast metadata):

GET /v1/threads

Returnerar { threads: [...] } för den aktuella profilen med messages borttaget (använd detalj-slutpunkten när du behöver dem). Alla andra fält bevaras — id, title, createdAt, updatedAt, modeId, archived, användningsstatistik, plus subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId när dessa är angivna. (Den mer omfattande nyttolasten är exklusiv för API:et — WebSocket-sändningen till sidofältet använder en striktare begränsning för att hålla sig under transportgränserna.)

Hämta en tråd med alla meddelanden:

GET /v1/threads/{id}

Returnerar den fullständiga tråden inklusive dess messages-array — varje användarmeddelande, svar från assistenten, verktygsanrop och verktygsresultat.

Hämta endast meddelanden:

GET /v1/threads/{id}/messages

Returnerar endast messages-arrayen — lättare än det fullständiga trådobjektet när du bara behöver konversationen.

Skapa en tråd:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

Returnerar 201 med { thread }. Den nya tråden visas omedelbart i sidofältet (via WebSocket-sändning). API:et växlar aldrig appens aktiva tråd vid skapande — anropa PUT /v1/threads/active separat om du önskar det.

Uppdatera en tråd:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

Uppdateringsbara fält: title, modeId, archived, lastUsedModel. Ändringar sänds till sidofältet i realtid.

Radera en tråd:

DELETE /v1/threads/{id}

Mjukraderar tråden (tombstone för synkronisering). Returnerar 204. Raderade trådar flyttas till papperskorgen och kan återställas tills papperskorgen töms.

Aktiv tråd:

GET /v1/threads/active            # Returnerar { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

Hantering av papperskorg:

GET /v1/threads/trash/count       # Returnerar { count }
POST /v1/threads/trash/empty      # Returnerar { deletedCount, protectedCount }

Skyddade trådar (som behålls via inställningen för datalagring) exkluderas vid tömning av papperskorgen.

Fortsätta en konversation via API:et: För att skicka ett uppföljningsmeddelande till en befintlig tråd, använd POST /v1/runs med trådens ID:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

Agenten ser hela konversationshistoriken från tråden.

Bilagor

Bilagor är filer länkade till trådar — skärmdumpar, PDF-filer, dokument, uppladdade bilder, genererade artefakter. API:et låter dig lista, ladda upp, ladda ner och hantera dem.

Lista alla bilagor (endast metadata):

GET /v1/attachments

Returnerar metadata för bilagor för den aktuella profilen. Tunga fält (dataUrl, extractedContent, extractedImages) är borttagna — använd slutpunkterna för detaljer eller innehåll för dessa.

Lista bilagor för en specifik tråd:

GET /v1/threads/{threadId}/attachments

Hämta metadata för bilaga:

GET /v1/attachments/{id}

Returnerar fullständig metadata inklusive extractedContent (OCR-text, tolkad markdown), contentType, fileName, size och en hasContent-flagga. Den råa binärfilen ingår INTE — använd /content-slutpunkten för det.

Ladda ner binärfil för bilaga:

GET /v1/attachments/{id}/content

Returnerar den råa filen med korrekta Content-Type- och Content-Disposition-huvuden. Skicka detta till en fil:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

Ladda upp en bilaga:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "Kvartalsrapport",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl är en base64-kodad data-URL. Returnerar 201 med det nya bilage-ID:t. Bilagan länkas till den angivna tråden.

Uppdatera metadata för bilaga:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "Uppdaterad beskrivning", "fileName": "nytt-namn.pdf" }

Ta bort en bilaga:

DELETE /v1/attachments/{id}

Mjukraderar via tombstone. Returnerar 204.

MCP-servrar

Hantera dina anslutningar till MCP (Model Context Protocol)-servrar — de servrar som ger agenter åtkomst till externa verktyg och datakällor.

Lista konfigurerade servrar:

GET /v1/mcp-servers

Returnerar alla MCP-serverkonfigurationer för den aktuella profilen. Känsliga fält (authToken, env, credentialId) rensas från svaret.

Hämta en servers konfiguration:

GET /v1/mcp-servers/{id}

Lägg till en ny MCP-server:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

För fjärrstyrda HTTP-servrar, använd "url" istället för "command":

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

Accepterade valfria fält vid POST: command, args, env, url, description, transportType, authType, authToken, authHeader, headers, specType, specPath, timeoutMs, credentialId, oauthConnectionId, approval. Serverhanterade fält (customOAuth, hubPackageId, profileId, connectorId, teamPublished, teamOrgId, vectorClock, ...) kan inte ställas in via API:et.

Uppdatera en server:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

Fält som kan ändras via PATCH speglar tillåtelse-listan för POST (inklusive credentialId och oauthConnectionId — praktiskt för att rotera en OAuth-anslutning utan att behöva radera och återskapa). Serverhanterade fält förblir skrivskyddade.

Aktivera/inaktivera en server:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

Radera en server:

DELETE /v1/mcp-servers/{id}

Processhantering

För lokala (stdio) MCP-servrar kan du hantera serverprocessen direkt.

Lista pågående processer:

GET /v1/mcp-servers/processes

Returnerar pågående serverprocesser med pid, startedAt och status för running.

Starta en server:

POST /v1/mcp-servers/{id}/start

Läser command/args/env från serverkonfigurationen och startar processen. Returnerar processens status.

Stoppa en server:

POST /v1/mcp-servers/{id}/stop

Stänger ner serverprocessen på ett kontrollerat sätt (SIGTERM med fallback till SIGKILL).

Anropa en JSON-RPC-metod direkt:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

Skickar en rå JSON-RPC 2.0-förfrågan till servern och returnerar resultatet. Användbart för felsökning eller för att anropa metoder som inte exponeras via verktygs-API:et.

Verktyg & Verktygslådor

Bläddra bland och anropa de verktyg som agenter använder — webbsökning, sök, kalender, Gmail, Slate och mer.

Lista verktygslådor (grupperade):

GET /v1/toolkits

Returnerar inbyggda verktyg grupperade efter kategori (Produktivitet, Sök, Verktyg, etc.) och alla anslutna MCP-servrar som separata verktygslådor, var och en med sina tillhörande åtgärder listade.

Lista alla verktyg (platt):

GET /v1/tools
GET /v1/tools?source=embedded   # Endast inbyggda verktyg
GET /v1/tools?source=mcp        # Endast MCP-serververktyg

Hämta verktygsdetaljer med indataschema:

GET /v1/tools/calculator

Returnerar { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }.

Fält	Betydelse
`inputSchema`	JSON Schema för verktygets indata — validera före anrop
`actions`	Valfria underåtgärder (t.ex. Slate `read`/`write`); varje har `id`, `displayName`, `description`, valfri `requiredTier`
`requiredTier`	Minsta användarnivå (`free` om utelämnad). Anrop via publikt API nekar allt över `free`
`requiredRuntimes`	Plattformar där detta verktyg är tillgängligt (`macos`, `ios`, etc.); utelämna ⇒ överallt
`riskTier`	Samtyckesrisk: `low` (standard), `medium`, `high`
`riskExplanation`	Mänskligt läsbar anledning till att `riskTier` är förhöjd
`requiresApproval`	`true` när verktyget kräver användargodkännande per anrop — anrop via publikt API nekar dessa

Anropa ett verktyg direkt:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" }, "threadId": "optional-thread-id" }

Returnerar { result }. Indata valideras mot verktygets schema — ogiltig indata returnerar 422 med detaljer. Skicka med ett valfritt threadId om verktyget behöver kontext bunden till en tråd (t.ex. sökning efter bilagor).

Gating — vad det publika API:et nekar:

Nivåbegränsade verktyg (metadata.requiredTier !== 'free') → 403. Agent-loopen kontrollerar nivå mot användarens session; det publika API:et har ingen medföljande nivåkontext, så den konservativa policyn är att neka. Använd POST /v1/runs med en agent som har rätt nivå istället.
Verktyg som kräver godkännande (metadata.approval.requiresApproval === true) → 403. Det finns ingen människa i loopen att fråga. Anropa via POST /v1/runs (vilket visar frågan för användaren) eller ställ in verktygets godkännandeläge till approve_all i appen för att kringgå detta.
Fjärrstyrda MCP-verktyg → 501 med vägledning att använda /v1/runs (de kräver agentens underprocess-transport).

Vision och bildanvändande verktyg: ladda upp via POST /v1/attachments först, skicka sedan det returnerade bilage-ID:t inuti input (t.ex. { "input": { "attachment_id": "att_abc", "prompt": "Vad finns i den här bilden?" } }). Verktyget läser binärfilen från lagringen via threadId; du skickar inte bytes inline.

Anslutningar

Hantera OAuth-integrationer — Google, Microsoft, GitHub, Notion, Slack med flera.

Bläddra bland tillgängliga integrationer:

GET /v1/connectors/catalog

Returnerar alla registrerade OAuth-leverantörer med namn, kategori och standardomfång.

Lista dina anslutna konton:

GET /v1/connectors

Returnerar aktiva anslutningar för den aktuella profilen. Tokens exponeras aldrig — endast metadata (leverantör, e-post, status, omfång, tidsstämplar).

Hämta en enskild anslutning:

GET /v1/connectors/{id}

Returnerar metadata för en anslutning (leverantör, e-post, status, omfång, tidsstämplar). Tokens exponeras aldrig.

Kontrollera anslutningens hälsa:

POST /v1/connectors/{id}/test

Returnerar { health: { status, isTokenExpired, canRefresh } }.

Ta bort en anslutning:

DELETE /v1/connectors/{id}

Att skapa nya anslutningar kräver det interaktiva OAuth-flödet via appens gränssnitt eller /auth/*-rutterna.

Utlösare

Schemalägg agenter att köras automatiskt — dagliga briefar, veckorapporter, intervallbaserad övervakning.

Varje utlösare har en kind-diskriminator: schedule (standard — körs efter klockan), webhook (körs när en extern tjänst gör en POST till webhook-sökvägen) eller messaging (körs från en ansluten meddelandeadapter — t.ex. inkommande Slack/Discord-meddelanden som matchar ett kanalfilter).

Lista utlösare:

GET /v1/triggers

Returnerar { triggers: [...] }. Varje post inkluderar dess kind, schema och kind-specifika fält (t.ex. webhookSecret/webhookPath för webhook-utlösare, messagingAdapterId/messagingChannelFilter for messaging-utlösare).

Hämta en enskild utlösare:

GET /v1/triggers/{id}

Skapa en schemalagd utlösare:

POST /v1/triggers
Content-Type: application/json

{
  \"name\": \"Morgonbriefing\",
  \"prompt\": \"Sammanfatta mina olästa e-postmeddelanden och dagens kalender\",
  \"modeId\": \"general\",
  \"schedule\": { \"type\": \"daily\", \"time\": \"08:00\" }
}

Schematyper som stöds:

{ \"type\": \"interval\", \"minutes\": 60 } — var N:e minut (min 15, max 1440)
{ \"type\": \"daily\", \"time\": \"09:00\" } — dagligen vid en specifik tid
{ \"type\": \"weekly\", \"day\": \"mon\", \"time\": \"09:00\" } — varje vecka
{ \"type\": \"weekdays\", \"time\": \"08:30\" } — måndag till fredag
{ \"type\": \"daysOfWeek\", \"days\": [\"mon\", \"wed\", \"fri\"], \"time\": \"10:00\" } — specifika dagar
{ \"type\": \"monthly\", \"dayOfMonth\": 1, \"time\": \"09:00\" } — varje månad
{ \"type\": \"manual\" } — endast när den utlöses via API

Utlös en utlösare manuellt:

POST /v1/triggers/{id}/fire

Returnerar 202 med ett threadId för den resulterande körningen.

Uppdatera eller radera:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

Webhooks

Webhook-triggers låter externa tjänster (CI/CD, övervakning, formulärbyggare) utlösa en agentkörning via HTTP.

Skapa en webhook-trigger:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Deploy hook",
  "prompt": "En driftsättning har skett: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

Returnerar 201 med en webhookSecret och webhookPath. Spara hemligheten — du behöver den för att signera nyttolaster.

Skicka en webhook:

# Beräkna HMAC-SHA256 av den råa anropskroppen
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

Webhook-slutpunkten kräver INTE bearer-autentisering — den använder HMAC-verifiering istället. Returnerar 202 med threadId för den skickade körningen. Platshållaren {{webhook.body}} i triggerns prompt ersätts med den råa anropskroppen.

Meddelandetrigger

Meddelandetrigger aktiveras när en ansluten meddelandeadapter (t.ex. en Slack- eller Discord-integration installerad via Community Hub) tar emot ett inkommande meddelande som matchar triggerns filter. Skapa med kind: "messaging":

POST /v1/triggers
Content-Type: application/json

{
  "name": "Omnämnandesvarare",
  "prompt": "Svara hjälpsamt på: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

Adaptern ansvarar för att skicka matchande händelser till triggern; messagingChannelFilter är adapterspecifik.

Anpassade funktioner

Skapa dina egna verktyg som agenter kan anropa. Funktioner skrivs i JavaScript eller Python och körs i en sandlåda.

Lista funktioner:

GET /v1/functions

Skapa en funktion:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "Beräkna BMI från längd och vikt",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

JavaScript-funktioner tar emot input och måste returnera ett resultat. Python-funktioner sätter en result-variabel:

# Python-exempel
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

Kör en funktion direkt:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

Säkerhet: JavaScript körs i Nodes vm-sandlåda (ingen åtkomst till filsystem eller nätverk, 10s timeout). Python körs som en underprocess med 30s timeout. Båda validerar indata före körning.

Uppdatera eller ta bort:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

Färdigheter

Färdigheter är sparade prompter som agenter kan referera till och snabbstarta från vyn för tom konversation. Hub-installerade färdigheter (hanterade via paketinstallation) inkluderas INTE här — endast användarskapade färdigheter listas och är redigerbara.

Lista färdigheter:

GET /v1/skills

Returnerar { skills: [...] } med användarskapade färdigheter för den aktiva profilen. Rensade färdigheter, hub-överlagringar och synkskuggor filtreras bort.

Hämta en färdighet:

GET /v1/skills/{id}

Skapa en färdighet:

POST /v1/skills
Content-Type: application/json

{
  "prompt": "Sammanfatta sidan i 3 punkter.",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Snabbsammanfattning",
  "description": "Tre punkters TL;DR av den aktiva sidan"
}

Endast prompt krävs. modes (valfritt) begränsar färdigheten till specifika agent-ID:n; utelämna för alla lägen. Returnerar 201 med den nya färdigheten (inklusive server-tilldelat id, createdAt, updatedAt).

Uppdatera en färdighet:

PATCH /v1/skills/{id}
Content-Type: application/json

{ "prompt": "Uppdaterad prompt", "isFavorite": false }

Fält som kan uppdateras: prompt, tags, modes, displayName, description, isFavorite. Försök att uppdatera en hub-överlagrad färdighet returnerar 404.

Radera en färdighet:

DELETE /v1/skills/{id}

Mjukraderar via tombstone. Returnerar 204. Hub-överlagrade färdigheter returnerar 404 — avinstallera källpaketet istället.

Arbetsflöden

Orkestrera flera agenter i en DAG (riktad acyklisk graf) — kör steg parallellt där det är möjligt, och skicka utdata från tidigare steg till senare.

Validera en arbetsflödesgraf:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Undersök trender för förnybar energi" },
      { "id": "analyze", "agentId": "general", "prompt": "Undersök konkurrentprissättning" },
      { "id": "report", "agentId": "general", "prompt": "Skriv en rapport som kombinerar: {{outputs.research}} och {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

Returnerar { valid: true/false, errors: [...] }. Kontrollerar efter cykler, dubblett-ID:n och saknade beroendereferenser.

Kör ett arbetsflöde:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Undersök trender för förnybar energi" },
      { "id": "summarize", "agentId": "general", "prompt": "Sammanfatta: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

Returnerar { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

Oberoende noder (utan delade beroenden) körs parallellt. Platshållaren {{outputs.nodeId}} i en nods prompt ersätts med innehållet från den namngivna uppströmsnoden. Varje nod är en fullständig agentkörning, så den kan använda verktyg, surfa på webben och få tillgång till alla funktioner hos målagenten.

Kunskapsbaser

Organisera dokument i sökbara samlingar som agenter kan referera till.

Lista kunskapsbaser:

GET /v1/knowledge/bases

Skapa en kunskapsbas:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "Forskningsrapporter" }

Returnerar 201 med det nya bas-ID:t.

Ladda upp ett dokument till en kunskapsbas:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Trender för förnybar energi 2026"
}

Fältet dataUrl är en base64-kodad data-URL. Returnerar 201 med dokumentets metadata.

Lista dokument i en kunskapsbas:

GET /v1/knowledge/bases/{id}/documents

Sök inom en kunskapsbas:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "förnybar energi" }

Returnerar matchande dokument baserat på filnamn och beskrivning. Semantisk (vektor) sökning kommer i en framtida utgåva.

Ta bort ett dokument eller en kunskapsbas:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

Exportera & importera agenter

Dela agenter som bärbara paket — mellan enheter, team eller Community Hub.

Exportera en agent:

POST /v1/agents/{id}/export

Returnerar ett JSON-paket som innehåller agentdefinitionen, verktygskrav (härledda från aktiverade verktyg), anslutningskrav (vilka OAuth-leverantörer som behövs) och utlösarmallar. Synk-metadata tas bort — paketet är en ren, fristående ritning.

Importera en agent:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"delad-research-agent\",
      \"branding\": { \"name\": \"Research-agent\", \"description\": \"Från teamet\" },
      \"defaultSettings\": { \"systemPrompt\": \"Du forskar om saker.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Returnerar 201 med den installerade agenten. ID-kollisioner med inbyggda eller befintliga agenter returnerar 409.

Felhantering

API:et använder standard HTTP-statuskoder:

Kod	Betydelse
`200`	Lyckades
`201`	Skapad
`202`	Accepterad (asynkron åtgärd startad)
`204`	Raderad (inget innehåll)
`400`	Felaktig begäran — kontrollera fältet `error` för detaljer
`401`	Obehörig — saknad eller ogiltig sessionshemlighet
`403`	Förbjudet — t.ex. försök att ändra en inbyggd agent
`404`	Hittades inte
`409`	Konflikt — t.ex. agent-ID finns redan
`422`	Valideringsfel — indata matchar inte verktygets schema
`429`	Hastighetsbegränsad — se budgetar för hastighetsbegränsning i avsnittet Autentisering
`500`	Serverfel — kontrollera fältet `error`
`501`	Ej implementerat — funktionen finns men är inte tillgänglig på detta sätt
`503`	Tjänsten är inte tillgänglig — lagring eller leverantör är inte redo

Alla felsvar inkluderar { "error": "mänskligt läsbart meddelande" }.

Snabbstarts-exempel

Här är ett komplett arbetsflöde: skapa en agent, kör den och strömma resultaten.

# 1. Skapa en anpassad agent
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "Sammanfatta all indata kortfattat i 3 punkter.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Kör den asynkront
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "Sammanfatta https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. Strömma händelserna
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. Exportera agenten för delning
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.