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ör agenter, hantera verktyg, schemalägg uppgifter och mer. API:et finns 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-reglaget i inställningarna:

För externa konsumenter (skript, integrationer, curl): Ställ in en API-åtkomsttoken i Inställningar > API-åtkomst, och 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 autentiseras automatiskt via den befintliga relay-auth-headern (X-Relay-Auth). Ingen manuell konfiguration krävs – appen hanterar detta bakom kulisserna.

Konfiguration:

  1. Öppna Caiioo Inställningar > API-åtkomst
  2. Slå på Aktivera offentligt API
  3. Ange en API-åtkomsttoken (valfri sträng du väljer – hantera den som ett lösenord)
  4. Använd den token i alla API-anrop

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 instruktioner.

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 alla konfigurerade leverantörstyper (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten och andra allt eftersom de läggs till) med funktionsflaggor (supportsVision, supportsToolCalling, supportsStreaming, etc.) och huruvida en API-nyckel är konfigurerad.

Lista modeller för en leverantör:

GET /v1/providers/anthropic/models

Returnerar modellkatalogen för den leverantören. Varje modell inkluderar id, displayName och contextLength där det är tillgängligt.

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.

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å fel returneras 500 med { error, status: "error" }.

Asynkront läge

Skicka och glöm — användbart för tidskrävande uppgifter:

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

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

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

Fråga efter 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 sker: GENERATION_STARTED, STREAMING_CONTENT, verktygsanrop, underagentsaktivitet och den avslutande händelsen (GENERATION_COMPLETE, GENERATION_ERROR eller GENERATION_CANCELLED). Strömmen avslutas efter den sista händelsen.

Avbryt en körning:

POST /v1/runs/{runId}/cancel

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

Threads

Threads är konversationer. Varje agentkörning sker inom en thread, och threads sparas mellan sessioner. API:et låter dig lista, läsa, skapa och hantera threads programmatiskt.

Lista alla threads (endast metadata):

GET /v1/threads

Returnerar threads för den aktuella profilen med meddelanden borttagna för prestanda. Varje thread inkluderar id, title, createdAt, updatedAt, modeId, archived och användningsstatistik.

Hämta en thread med fullständiga meddelanden:

GET /v1/threads/{id}

Returnerar den kompletta threaden inklusive dess messages-array — varje användarmeddelande, assistant-svar, tool-anrop och tool-resultat.

Hämta endast meddelanden:

GET /v1/threads/{id}/messages

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

Skapa en thread:

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

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

Returnerar 201 med den nya threaden. Som standard byter API:et INTE appens aktiva thread — skicka med "setActive": true i body om du vill det. Den nya threaden visas omedelbart i sidofältet (via WebSocket-sändning).

Uppdatera en thread:

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 thread:

DELETE /v1/threads/{id}

Gör en mjuk radering av threaden (tombstone för synkronisering). Returnerar 204. Raderade threads flyttas till papperskorgen och kan återställas tills papperskorgen töms.

Aktiv thread:

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 threads (som behålls via inställningen för datalagring) exkluderas när papperskorgen töms.

Fortsätta en konversation via API: För att skicka ett uppföljningsmeddelande till en befintlig thread, använd POST /v1/runs med threadens 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 threaden.

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 MCP (Model Context Protocol) serveranslutningar — servrarna som ger agenter tillgång 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"
}

Uppdatera en server:

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

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

Aktivera/inaktivera en server:

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

{ "enabled": false }

Ta bort 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 listade åtgärder.

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 verktygets JSON-schema för dess indataparametrar, så att du kan validera före anrop.

Anropa ett verktyg direkt:

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

{ "input": { "expression": "sqrt(144) + 3^2" } }

Returnerar { result }. Indata valideras mot verktygets schema — ogiltig indata returnerar 422 med detaljer. Fjärrstyrda MCP-verktyg returnerar 501 med vägledning att använda /v1/runs istället (de kräver agentens subprocess-transport).

Anslutningar

Hantera OAuth-integrationer — Google, Microsoft, GitHub, Notion, Slack och mer.

Bläddra i 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).

Kontrollera anslutningshä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.

Triggers

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

Lista triggers:

GET /v1/triggers

Skapa en schemalagd trigger:

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

Typer av scheman 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" } — veckovis
  • { "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" } — månatligen
  • { "type": "manual" } — endast när den aktiveras via API

Aktivera en trigger manuellt:

POST /v1/triggers/{id}/fire

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

Uppdatera eller ta bort:

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 trigger-prompten ersätts med den råa anropskroppen.

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}

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 verktygsschemat
500 Serverfel — kontrollera fältet error
501 Ej implementerat — funktionen finns men är inte tillgänglig på detta sätt
503 Tjänsten ej tillgänglig — lagring eller leverantö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.