זוהי תרגום מכונה של המסמך המקורי באנגלית. במקרה של סתירה בין תרגום זה לבין הגרסה המקורית באנגלית, הגרסה באנגלית היא הקובעת. קרא את הגרסה המקורית באנגלית

API ציבורי

Caiioo כוללת REST API המאפשר לך לשלוט בהכל באופן תכנותי: הרצת סוכנים, ניהול כלים, תזמון משימות ועוד. ה-API חי על אותו שרת מקומי שמפעיל את אפליקציית שולחן העבודה ואת ה-bridge של הדפדפן.

Base URL: http://localhost:3847/v1

אימות: שתי דרכים לאימות, שתיהן מותנות בהפעלת מתג ה-API בהגדרות:

עבור צרכנים חיצוניים (סקריפטים, אינטגרציות, curl): הגדר טוקן גישה ל-API בהגדרות > גישת API, ואז השתמש בו כטוקן Bearer:

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

עבור האפליקציה המקומית (אוטומטי): אפליקציית שולחן העבודה של Caiioo, תוספי הדפדפן והאפליקציות לנייד מתאמתים אוטומטית דרך כותרת ה-relay auth הקיימת (x-relay-auth; כותרות HTTP אינן רגישות לאותיות גדולות/קטנות). אין צורך בהגדרה ידנית — האפליקציה מטפלת בזה מאחורי הקלעים. בקשות Relay-auth עוקפות את מתג ה-Enable Public API מכיוון שהן כבר מהימנות; רק בקשות bearer-token מותנות במתג.

הגדרה:

פתח את הגדרות Caiioo > גישת API
הפעל את Enable Public API
הגדר API access token (כל מחרוזת שתבחר — התייחס אליה כאל סיסמה)
השתמש בטוקן זה בכל בקשות ה-API

ה-API זמין ב-localhost ודרך ה-relay הפרטי. בדוק את GET /v1/auth/info (אין צורך באימות) לסטטוס נוכחי והוראות הגדרה.

מגבלות קצב: כל בקשת /v1/* מוגבלת בקצב לכל IP של לקוח — 100 בקשות GET לדקה לקריאה ו-30 בקשות כתיבה לדקה (POST / PATCH / DELETE) משולבות. בקשות מעבר למגבלה יקבלו 429. משלוחי Webhook‏ (POST /v1/webhooks/:id) אינם דורשים אימות bearer ואינם כפופים למגבלות אלו.

פרופילים

מכשיר בודד יכול להכיל מספר פרופילי משתמש (למשל אישי + עבודה). ה-API מאפשר לסקריפטים חיצוניים לבדוק את הפרופילים הזמינים ולהחליף את הפרופיל הפעיל לפני ביצוע עבודה אחרת. יצירה, עדכון ומחיקה של פרופילים אינם נחשפים במכוון דרך ה-API הציבורי — תהליכים אלו שייכים לממשק ה-onboarding של האפליקציה.

רשימת פרופילים:

GET /v1/profiles

מחזיר { profiles: [...] } עם רשומה אחת לכל פרופיל שלא נמחק. כל רשומה כוללת id, name, email, avatarUrl, tier, accessibleModes, license, organization, preferences, onboardingComplete, createdAt, lastAccessedAt. שדות המכילים טוקנים (serviceCredentials, oauthConnections) ופרטי סנכרון פנימיים (vectorClock, lastModifiedBy) מוסרים. השתמש ב-/v1/connectors כדי לבדוק חיבורי OAuth.

קבלת הפרופיל הפעיל:

GET /v1/profiles/active

מחזיר את ה-{ profile } עבור הפרופיל שנמצא כעת בשימוש על ידי שרת זה. כל משאבי ה-/v1/* המשויכים לפרופיל (threads, attachments, settings, skills) פועלים מול פרופיל זה.

החלפת הפרופיל הפעיל:

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

{ "profileId": "user-uuid-from-list" }

מחזיר את ה-{ profile } עבור הפרופיל הפעיל החדש. מחזיר 404 אם המזהה אינו פרופיל מוכר.

ספקים ומודלים (Providers & Models)

גלה אילו ספקי LLM מוגדרים ואילו מודלים זמינים.

רשימת ספקים:

GET /v1/providers

מחזיר את כל סוגי הספקים הנתמכים. כרגע: anthropic, openai, google, openrouter, ollama, poe, mlx, perplexity, baseten, cloudflare. כל רשומה כוללת את השדות type, displayName, icon, requiresApiKey, hasApiKey, ואובייקט capabilities עם הדגלים המפורטים להלן.

דגל יכולת (Capability flag)	משמעות
`supportsVision`	הספק יכול לקבל קלטי תמונה
`supportsPdfFile`	הספק יכול לקבל בלוקים של תוכן קובצי PDF גולמיים באופן טבעי (natively)
`supportsToolCalling`	הספק תומך בקריאה לפונקציות/כלים (function/tool calling)
`supportsStreaming`	הספק מזרים (streams) טוקנים באופן הדרגתי
`supportsExtendedThinking`	הספק חושף תקציב חשיבה/הסקה (reasoning/thinking budget)
`supportsPromptCaching`	הספק תומך בהנחיות לשמירת זיכרון מטמון של פרומפטים (prompt-cache)
`nativeReasoningBlocks`	הספק מפיק חשיבה כבלוקים של הודעות טבעיות (לעומת טקסט)
`requiresThoughtSignature`	הספק דורש שטוקני חשיבה חתומים יוחזרו אליו (echoed back)

דגלי היכולות משקפים את שדה ה-readonly capabilities של כל מחלקת ספק (ראה src/shared/providers/*-provider.ts) ומאומתים על ידי בדיקת drift sentinel — מומלץ לקרוא לנקודת קצה זו בזמן ריצה במקום להזין את המטריצה בקוד באופן קשיח.

הערות עבור ספקי BYOK:

perplexity חושף רשימה נבחרת של מודלי Sonar (ל-Perplexity אין נקודת קצה ציבורית של /models).
cloudflare (AI Gateway) הוא BYOK + רב-ספקים; רשימת המודלים נקבעת על פי תצורת ה-gateway שלך ומוחזרת כמערך ריק על ידי /v1/providers/cloudflare/models. השתמש בקטלוג ה-gateway שלך.

רשימת מודלים עבור ספק:

GET /v1/providers/openrouter/models

מחזיר את קטלוג המודלים עבור אותו ספק. כל מודל כולל id, displayName, ו-contextLength במידה וזמין. מחזיר 503 כאשר לספק חסר מפתח API או כאשר הקטלוג החיצוני שלו אינו נגיש.

קטלוג שטוח של כל הספקים:

GET /v1/models

ממזג מודלים מכל ספק מוגדר לרשימה אחת. ספקים ללא מפתחות API יושמטו ויופיעו תחת warnings.

סוכנים

סוכנים הם הלב של caiioo. כל סוכן הוא מצב (Mode) — אישיות מוגדרת עם הנחיית מערכת, כלים, משתנים ומיומנויות משלה.

רשימת כל הסוכנים:

GET /v1/agents

מחזיר סוכנים מובנים (קניות, מקום עבודה, כללי) וכל סוכן מותאם אישית שיצרת. כל אחד מתויג עם source: \"builtin\" או source: \"custom\".

יצירת סוכן מותאם אישית:

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

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"סוכן מחקר\",
    \"description\": \"מחפש באינטרנט ומסכם ממצאים\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"אתה עוזר מחקר. צטט תמיד מקורות.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

מחזיר 201 עם הסוכן שנוצר. שעון וקטורי מצורף אוטומטית לסנכרון.

עדכון סוכן:

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

{ \"branding\": { \"name\": \"סוכן מחקר\", \"description\": \"תיאור מעודכן\" } }

ממזג את העדכון לסוכן הקיים ומקדם את השעון הווקטורי. סוכנים מובנים יחזירו 403 — הם לקריאה בלבד.

מחיקת סוכן:

DELETE /v1/agents/my-research-agent

מחיקה רכה דרך tombstone (מסתנכרן בין מכשירים). מחזיר 204.

הרצת סוכנים (Agents)

זהו האירוע המרכזי — הפעלת סוכן לעיבוד הודעה.

גוף הבקשה — שדות נתמכים

שדה	חובה	תיאור
`agentId`	כן	מזהה מצב מובנה (למשל `general`) או מזהה סוכן מותאם אישית
`input.message`	כן	טקסט הודעת המשתמש
`input.attachments`	לא	מערך של מזהי קבצים מצורפים (שהועלו כבר דרך `/v1/attachments`) לצירוף לסבב זה
`input.variables`	לא	דריסות משתנים לכל הרצה המתמזגות לתוך ה-variable resolver של הסוכן
`input.tabContext`	לא	מחרוזת בפורמט חופשי המוזרקת כהקשר-דף (בשימוש על ידי ה-browser bridge)
`input.messageId`	לא	מזהה הודעה המסופק על ידי הלקוח — שימושי למניעת כפילויות (dedup) במקרה של ניסיון חוזר
`threadId`	לא	שרשור (thread) קיים להמשך. אם הושמט, ייווצר ויוחזר שרשור חדש
`mode`	לא	`"sync"` או `"async"`. ברירת המחדל היא `"async"`

מצב סינכרוני (Synchronous Mode)

המתנה לתגובה המלאה:

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

{
  "agentId": "general",
  "input": { "message": "What's the weather in Paris today?" },
  "mode": "sync"
}

מחזיר 200 עם { content, usage, status: "completed" } לאחר שהסוכן מסיים. אם הסוכן נתקל בשגיאה, מחזיר 500 עם { error, status: "error" }. הרצות סינכרוניות יגיעו ל-timeout לאחר 5 דקות עם status: "error" אם לא התקבל אירוע סיום — השתמשו ב-async + SSE עבור כל פעולה שעשויה להימשך זמן רב יותר.

מצב אסינכרוני (Asynchronous Mode)

"שלח ושכח" — שימושי למשימות ארוכות:

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

{
  "agentId": "my-research-agent",
  "input": { "message": "Write a 2000-word analysis of renewable energy trends" },
  "mode": "async"
}

מחזיר 202 באופן מיידי עם { runId, threadId, status: "running" }.

בדיקת סטטוס (Polling):

GET /v1/runs/{runId}

מחזיר { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. הסטטוס הוא אחד מתוך running, completed, error, או cancelled.

הזרמת אירועים בזמן אמת (SSE):

GET /v1/runs/{runId}/events

מחזיר text/event-stream עם כל אירוע סוכן כפי שהוא מתרחש: GENERATION_STARTED, STREAMING_CONTENT, קריאות לכלים (tool calls), פעילות סוכני-משנה (subagent activity), ואירוע הסיום (GENERATION_COMPLETE, GENERATION_ERROR, או GENERATION_CANCELLED).

לאחר אירוע הסיום, השרת פולט מסגרת SSE אחרונה עם event: terminal וגוף נתונים (payload) ריק כסימן מפורש לסיום הזרם, ואז סוגר את החיבור. על הלקוחות להתייחס לקבלת מסגרת זו (או לסגירת החיבור) כאות להפסקת הקריאה.

אם נרשמתם (subscribe) לאחר שההרצה כבר הסתיימה, השרת ישדר שוב מסגרת אחת מסוג RUN_SNAPSHOT המכילה את ה-record הסופי המלא, ולאחריה את סימן ה-event: terminal, ואז ייסגר.

ביטול הרצה:

POST /v1/runs/{runId}/cancel

מחזיר { run: { ..., status: "cancelled" } }.

Threads

Threads הם שיחות. כל הרצה של סוכן מתרחשת בתוך thread, ו-threads נשמרים לאורך סשנים. ה-API מאפשר לך להציג, לקרוא, ליצור ולנהל threads באופן פרוגרמטי.

רשימת כל ה-threads (מטא-דאטה בלבד):

GET /v1/threads

מחזיר { threads: [...] } עבור הפרופיל הנוכחי כאשר ה-messages מוסרים (השתמש בנקודת הקצה של הפירוט כשאתה זקוק להם). כל שדה אחר נשמר — id, title, createdAt, updatedAt, modeId, archived, סטטיסטיקות שימוש, בתוספת subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId כאשר הם מוגדרים. (ה-payload העשיר יותר בלעדי ל-API — שידור ה-sidebar ב-WebSocket משתמש בסינון הדוק יותר כדי להישאר תחת מגבלות התעבורה.)

קבלת thread עם הודעות מלאות:

GET /v1/threads/{id}

מחזיר את ה-thread המלא כולל מערך ה-messages שלו — כל הודעת משתמש, תגובת עוזר, קריאת כלי (tool call) ותוצאת כלי.

קבלת ההודעות בלבד:

GET /v1/threads/{id}/messages

מחזיר רק את מערך ה-messages — קל יותר מאובייקט ה-thread המלא כשאתה זקוק רק לשיחה.

יצירת thread:

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

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

מחזיר 201 עם { thread }. ה-thread החדש מופיע ב-sidebar באופן מיידי (דרך שידור WebSocket). ה-API לעולם אינו מחליף את ה-thread הפעיל באפליקציה בעת יצירה — קרא ל-PUT /v1/threads/active בנפרד אם ברצונך לעשות זאת.

עדכון thread:

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

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

שדות ניתנים לעדכון: title, modeId, archived, lastUsedModel. שינויים משודרים ל-sidebar בזמן אמת.

מחיקת thread:

DELETE /v1/threads/{id}

מבצע מחיקה רכה (soft-delete) ל-thread (סימון tombstone לסנכרון). מחזיר 204. threads שנמחקו עוברים לאשפה וניתן לשחזר אותם עד לריקון האשפה.

Thread פעיל:

GET /v1/threads/active            # מחזיר { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

ניהול אשפה:

GET /v1/threads/trash/count       # מחזיר { count }
POST /v1/threads/trash/empty      # מחזיר { deletedCount, protectedCount }

threads מוגנים (שנשמרו באמצעות מתג שמירת הנתונים) אינם נכללים בריקון האשפה.

המשך שיחה דרך ה-API: כדי לשלוח הודעת המשך ל-thread קיים, השתמש ב-POST /v1/runs עם ה-ID של ה-thread:

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

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

הסוכן רואה את היסטוריית השיחה המלאה מה-thread.

קבצים מצורפים

קבצים מצורפים הם קבצים המקושרים לשרשורים — צילומי מסך, קובצי PDF, מסמכים, תמונות שהועלו, תוצרים שנוצרו. ה-API מאפשר לך לרשום, להעלות, להוריד ולנהל אותם.

רשימת כל הקבצים המצורפים (מטא-דאטה בלבד):

GET /v1/attachments

מחזיר מטא-דאטה של קבצים מצורפים עבור הפרופיל הנוכחי. שדות כבדים (dataUrl, extractedContent, extractedImages) מושמטים — השתמש בנקודות הקצה של הפרטים או התוכן עבורם.

רשימת קבצים מצורפים עבור שרשור ספציפי:

GET /v1/threads/{threadId}/attachments

קבלת מטא-דאטה של קובץ מצורף:

GET /v1/attachments/{id}

מחזיר מטא-דאטה מלא כולל extractedContent (טקסט OCR, markdown מעובד), contentType, fileName, size, ודגל hasContent. הקובץ הבינארי הגולמי אינו כלול — השתמש בנקודת הקצה /content עבורו.

הורדת קובץ בינארי מצורף:

GET /v1/attachments/{id}/content

מחזיר את הקובץ הגולמי עם כותרות ה-Content-Type וה-Content-Disposition הנכונות. נתב זאת לקובץ:

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

העלאת קובץ מצורף:

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

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

ה-dataUrl הוא כתובת URL של נתונים בקידוד base64. מחזיר 201 עם מזהה הקובץ המצורף החדש. הקובץ המצורף מקושר לשרשור שצוין.

עדכון מטא-דאטה של קובץ מצורף:

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

{ "description": "Updated description", "fileName": "new-name.pdf" }

מחיקת קובץ מצורף:

DELETE /v1/attachments/{id}

מחיקה רכה באמצעות tombstone. מחזיר 204.

שרתי MCP

נהל את חיבורי שרתי ה-MCP (Model Context Protocol) שלך — השרתים המעניקים לסוכנים (agents) גישה לכלים חיצוניים ולמקורות נתונים.

רשימת שרתים מוגדרים:

GET /v1/mcp-servers

מחזיר את כל הגדרות שרתי ה-MCP עבור הפרופיל הנוכחי. שדות רגישים (authToken, env, credentialId) מוסרים מהתגובה.

קבלת הגדרות שרת:

GET /v1/mcp-servers/{id}

הוספת שרת MCP חדש:

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

עבור שרתי HTTP מרוחקים, השתמש ב-"url" במקום ב-"command":

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

שדות אופציונליים מקובלים ב-POST: ‏command, args, env, url, description, transportType, authType, authToken, authHeader, headers, specType, specPath, timeoutMs, credentialId, oauthConnectionId, approval. שדות המנוהלים על ידי השרת (customOAuth, hubPackageId, profileId, connectorId, teamPublished, teamOrgId, vectorClock, ...) אינם ניתנים להגדרה דרך ה-API.

עדכון שרת:

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

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

השדות הניתנים לעדכון (Patchable) תואמים לרשימת ההרשאות של POST (כולל credentialId ו-oauthConnectionId — שימושי להחלפת חיבור OAuth ללא צורך במחיקה ויצירה מחדש). שדות המנוהלים על ידי השרת נשארים לקריאה בלבד.

הפעלה/השבתה של שרת:

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

{ "enabled": false }

מחיקת שרת:

DELETE /v1/mcp-servers/{id}

ניהול תהליכים (Process Management)

עבור שרתי MCP מקומיים (stdio), ניתן לנהל את תהליך השרת באופן ישיר.

רשימת תהליכים רצים:

GET /v1/mcp-servers/processes

מחזיר תהליכי שרת פעילים עם pid, startedAt, וסטטוס running.

הפעלת שרת:

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

קורא את ה-command/args/env מהגדרות השרת ומריץ את התהליך. מחזיר את סטטוס התהליך.

עצירת שרת:

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

סוגר בצורה מסודרת את תהליך השרת (SIGTERM עם גיבוי של SIGKILL).

קריאה ישירה למתודת JSON-RPC:

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

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

שולח בקשת JSON-RPC 2.0 גולמית לשרת ומחזיר את התוצאה. שימושי לניפוי שגיאות (debugging) או לקריאה למתודות שאינן חשופות דרך ה-API של הכלים.

כלים וערכות כלים (Toolkits)

עיין והפעל את הכלים שבהם משתמשים סוכנים — גלישה באינטרנט, חיפוש, לוח שנה, Gmail, Slate ועוד.

רשימת ערכות כלים (מקובצות):

GET /v1/toolkits

מחזיר כלים מובנים המקובצים לפי קטגוריה (Productivity, Search, Utilities וכו') וכל שרתי MCP מחוברים כערכות כלים נפרדות, כאשר הפעולות של כל אחת מהן מפורטות.

רשימת כל הכלים (שטוחה):

GET /v1/tools
GET /v1/tools?source=embedded   # כלים מובנים בלבד
GET /v1/tools?source=mcp        # כלי שרת MCP בלבד

קבלת פרטי כלי עם סכימת קלט (input schema):

GET /v1/tools/calculator

מחזיר { tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }.

שדה	משמעות
`inputSchema`	JSON Schema עבור קלט הכלי — יש לאמת לפני ההפעלה
`actions`	תת-פעולות אופציונליות (למשל Slate `read`/`write`); לכל אחת יש `id`, `displayName`, `description`, ו-`requiredTier` אופציונלי
`requiredTier`	רמת המשתמש המינימלית (`free` אם הושמט). קריאה ל-API ציבורי תסרב לכל רמה מעל `free`
`requiredRuntimes`	פלטפורמות שבהן הכלי זמין (`macos`, `ios` וכו'); השמטה ⇒ זמין בכל מקום
`riskTier`	סיכון הסכמה: `low` (ברירת מחדל), `medium`, `high`
`riskExplanation`	סיבה קריאה לבני אדם לכך ש-`riskTier` מוגבה
`requiresApproval`	`true` כאשר הכלי דורש אישור משתמש לכל קריאה — קריאה ל-API ציבורי תסרב לאלו

הפעלת כלי ישירות:

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

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

מחזיר { result }. הקלט מאומת מול סכימת הכלי — קלט לא תקין מחזיר 422 עם פרטים. העבר threadId אופציונלי אם הכלי זקוק להקשר מוגדר-שרשור (למשל חיפוש קבצים מצורפים).

חסימה (Gating) — למה ה-API הציבורי מסרב:

כלים חסומים לפי רמה (Tier) (metadata.requiredTier !== 'free') ← 403. לולאת הסוכן בודקת את הרמה מול סשן המשתמש; ל-API הציבורי אין הקשר רמה מועבר, ולכן המדיניות השמרנית היא לסרב. השתמש ב-POST /v1/runs עם סוכן בעל הרמה המתאימה במקום זאת.
כלים הדורשים אישור (metadata.approval.requiresApproval === true) ← 403. אין אדם בתהליך (human in the loop) שניתן לשאול אותו. הפעל דרך POST /v1/runs (המציג את הבקשה למשתמש) או הגדר את מצב אישור הכלים ל-approve_all באפליקציה כדי לעקוף זאת.
כלי MCP מרוחקים ← 501 עם הנחיה להשתמש ב-/v1/runs (הם דורשים את תעבורת תת-תהליך הסוכן).

כלי ראייה ושימוש בתמונות: העלה דרך POST /v1/attachments תחילה, ולאחר מכן העבר את ה-ID של הקובץ המצורף שהתקבל בתוך ה-input (למשל { "input": { "attachment_id": "att_abc", "prompt": "What is in this image?" } }). הכלי קורא את הקובץ הבינארי מהאחסון דרך ה-threadId; אין להעביר את הבייטים (bytes) בתוך הקריאה.

מחברים (Connectors)

ניהול אינטגרציות OAuth — Google, Microsoft, GitHub, Notion, Slack ועוד.

עיון באינטגרציות זמינות:

GET /v1/connectors/catalog

מחזיר את כל ספקי ה-OAuth הרשומים עם שמם, הקטגוריה שלהם וההרשאות (scopes) המחדליות.

רשימת החשבונות המחוברים שלך:

GET /v1/connectors

מחזיר חיבורים פעילים עבור הפרופיל הנוכחי. טוקנים לעולם לא נחשפים — רק מטא-דאטה (ספק, אימייל, סטטוס, הרשאות, חותמות זמן).

קבלת חיבור בודד:

GET /v1/connectors/{id}

מחזיר מטא-דאטה עבור חיבור אחד (ספק, אימייל, סטטוס, הרשאות, חותמות זמן). טוקנים לעולם לא נחשפים.

בדיקת תקינות חיבור:

POST /v1/connectors/{id}/test

מחזיר { health: { status, isTokenExpired, canRefresh } }.

הסרת חיבור:

DELETE /v1/connectors/{id}

יצירת חיבורים חדשים דורשת תהליך OAuth אינטראקטיבי דרך ממשק המשתמש של האפליקציה או נתיבי ה-/auth/*.

טריגרים (Triggers)

תזמון סוכנים להרצה אוטומטית — תדרוכים יומיים, דוחות שבועיים, ניטור מבוסס מרווחי זמן.

לכל טריגר יש מבחין kind: ‏schedule (ברירת מחדל — מופעל לפי שעון), webhook (מופעל כששירות חיצוני שולח POST לנתיב ה-webhook), או messaging (מופעל ממתאם הודעות מחובר — למשל הודעות Slack/Discord נכנסות התואמות למסנן ערוץ).

רשימת טריגרים:

GET /v1/triggers

מחזיר { triggers: [...] }. כל רשומה כוללת את ה-kind שלה, לוח זמנים ושדות ספציפיים לסוג (למשל webhookSecret/webhookPath עבור טריגרים מסוג webhook,‏ messagingAdapterId/messagingChannelFilter עבור טריגרים מסוג הודעות).

קבלת טריגר בודד:

GET /v1/triggers/{id}

יצירת טריגר מתוזמן:

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

{
  "name": "Morning Briefing",
  "prompt": "Summarize my unread emails and today's calendar",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

סוגי לוחות זמנים נתמכים:

{ "type": "interval", "minutes": 60 } — כל N דקות (מינימום 15, מקסימום 1440)
{ "type": "daily", "time": "09:00" } — מדי יום בשעה ספציפית
{ "type": "weekly", "day": "mon", "time": "09:00" } — מדי שבוע
{ "type": "weekdays", "time": "08:30" } — בימי שני עד שישי
{ "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — ימים ספציפיים
{ "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — מדי חודש
{ "type": "manual" } — רק בהפעלה ידנית דרך ה-API

הפעלת טריגר ידנית:

POST /v1/triggers/{id}/fire

מחזיר 202 עם threadId עבור ההרצה שנוצרה.

עדכון או מחיקה:

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

Webhooks

טריגרים מסוג Webhook מאפשרים לשירותים חיצוניים (CI/CD, ניטור, בוני טפסים) להפעיל הרצת סוכן באמצעות HTTP.

יצירת טריגר webhook:

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

{
  "name": "Deploy hook",
  "prompt": "A deploy happened: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

מחזיר 201 עם webhookSecret ו-webhookPath. שמור את הסוד — תזדקק לו כדי לחתום על גופי הבקשה (payloads).

שליחת webhook:

# חישוב HMAC-SHA256 של גוף הבקשה הגולמי
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 אינה דורשת אימות bearer — היא משתמשת באימות HMAC במקום זאת. מחזיר 202 עם ה-threadId של ההרצה שנשלחה. מציין המיקום {{webhook.body}} בפרומפט של הטריגר יוחלף בגוף הבקשה הגולמי.

טריגרים של הודעות (Messaging triggers)

טריגרים של הודעות מופעלים כאשר מתאם הודעות מחובר (למשל אינטגרציית Slack או Discord שהותקנה דרך ה-Community Hub) מקבל הודעה נכנסת התואמת למסנן של הטריגר. צור עם kind: "messaging":

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

{
  "name": "Mention responder",
  "prompt": "Reply helpfully to: {{message.text}}",
  "modeId": "general",
  "kind": "messaging",
  "messagingAdapterId": "slack-team-acme",
  "messagingChannelFilter": "#support"
}

המתאם אחראי על שליחת אירועים תואמים לטריגר; ה-messagingChannelFilter הוא ספציפי למתאם.

פונקציות מותאמות אישית

צור כלים משלך שסוכנים יכולים לקרוא להם. פונקציות נכתבות ב-JavaScript או Python ורצות בתוך sandbox.

רשימת פונקציות:

GET /v1/functions

יצירת פונקציה:

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

{
  "name": "calculate_bmi",
  "description": "Calculate Body Mass Index from height and weight",
  "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 מקבלות input וחייבות להחזיר תוצאה. פונקציות Python מגדירות משתנה result:

# דוגמת Python
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

הפעלת פונקציה ישירות:

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

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

אבטחה: JavaScript רץ ב-sandbox של Node vm (ללא גישה למערכת הקבצים או לרשת, פסק זמן של 10 שניות). Python רץ כתת-תהליך עם פסק זמן של 30 שניות. שניהם מאמתים את הקלט לפני הביצוע.

עדכון או מחיקה:

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

מיומנויות (Skills)

מיומנויות הן פרומפטים שמורים שסוכנים יכולים להתייחס אליהם ולהפעיל במהירות מתצוגת שיחה ריקה. מיומנויות שהותקנו מה-Hub (המנוהלות דרך התקנת חבילה) אינן נכללות כאן — רק מיומנויות שנכתבו על ידי המשתמש מופיעות וניתנות לעריכה.

רשימת מיומנויות:

GET /v1/skills

מחזיר { skills: [...] } של מיומנויות שנכתבו על ידי המשתמש עבור הפרופיל הפעיל. מיומנויות שנמחקו, מיומנויות Hub-overlay ומיומנויות סנכרון מסוננות החוצה.

קבלת מיומנות אחת:

GET /v1/skills/{id}

יצירת מיומנות:

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

{
  "prompt": "Summarize the page in 3 bullet points.",
  "tags": ["utility", "summarize"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "Quick Summary",
  "description": "Three-bullet TL;DR of the active page"
}

רק שדה ה-prompt הוא חובה. השדה modes (אופציונלי) מגביל את המיומנות למזהי סוכנים ספציפיים; השמט עבור כל המצבים. מחזיר 201 עם המיומנות החדשה (כולל id, createdAt, updatedAt שהוקצו על ידי השרת).

עדכון מיומנות:

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

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

שדות ניתנים לעדכון: prompt, tags, modes, displayName, description, isFavorite. ניסיונות לעדכן מיומנות Hub-overlay יחזירו 404.

מחיקת מיומנות:

DELETE /v1/skills/{id}

מחיקה רכה. מחזיר 204. מיומנויות Hub-overlay יחזירו 404 — יש להסיר את חבילת המקור במקום זאת.

תהליכי עבודה (Workflows)

תזמור מספר סוכנים ב-DAG (גרף מכוון ללא מעגלים) — הרצת שלבים במקביל במידת האפשר, והזנת פלטים משלבים מוקדמים לשלבים מאוחרים יותר.

אימות גרף תהליך עבודה:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Research renewable energy trends" },
      { "id": "analyze", "agentId": "general", "prompt": "Research competitor pricing" },
      { "id": "report", "agentId": "general", "prompt": "Write a report combining: {{outputs.research}} and {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

מחזיר { valid: true/false, errors: [...] }. בודק מעגליות, מזהים כפולים והפניות חסרות לתלויות.

ביצוע תהליך עבודה:

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

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Research renewable energy trends" },
      { "id": "summarize", "agentId": "general", "prompt": "Summarize: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

מחזיר { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

צמתים עצמאיים (ללא תלויות משותפות) רצים במקביל. מציין המקום {{outputs.nodeId}} בהנחיית הצומת יוחלף בתוכן הפלט של הצומת הקודם שצוין. כל צומת הוא הרצת סוכן מלאה, כך שהוא יכול להשתמש בכלים, לגלוש באינטרנט ולגשת לכל היכולות של סוכן היעד.

מאגרי ידע

ארגון מסמכים באוספים הניתנים לחיפוש שסוכנים יכולים להתייחס אליהם.

רשימת מאגרי ידע:

GET /v1/knowledge/bases

יצירת מאגר ידע:

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

{ "name": "Research Papers" }

מחזיר 201 עם מזהה המאגר החדש.

העלאת מסמך למאגר ידע:

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

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Renewable energy trends 2026"
}

שדה ה-dataUrl הוא כתובת URL של נתונים בקידוד base64. מחזיר 201 עם המטא-דאטה של המסמך.

רשימת מסמכים במאגר ידע:

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

חיפוש בתוך מאגר ידע:

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

{ "query": "renewable energy" }

מחזיר מסמכים תואמים על סמך שם הקובץ והתיאור. חיפוש סמנטי (וקטורי) יתווסף בגרסה עתידית.

מחיקת מסמך או מאגר ידע:

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

ייצוא וייבוא סוכנים

שתף סוכנים כחבילות ניידות — בין מכשירים, צוותים או ב-Community Hub.

ייצוא סוכן:

POST /v1/agents/{id}/export

מחזיר חבילת JSON המכילה את הגדרת הסוכן, דרישות כלים (הנגזרות מכלים מופעלים), דרישות מחברים (אילו ספקי OAuth נדרשים) ותבניות טריגרים. מטא-נתוני סנכרון מוסרים — החבילה היא תוכנית נקייה ועצמאית.

ייבוא סוכן:

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

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"סוכן מחקר\", \"description\": \"מהצוות\" },
      \"defaultSettings\": { \"systemPrompt\": \"אתה חוקר דברים.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

מחזיר 201 עם הסוכן המותקן. התנגשויות מזהים (ID) עם סוכנים מובנים או קיימים יחזירו 409.

טיפול בשגיאות

ה-API משתמש בקודי סטטוס HTTP סטנדרטיים:

קוד	משמעות
`200`	הצלחה
`201`	נוצר
`202`	התקבל (פעולה אסינכרונית החלה)
`204`	נמחק (אין תוכן)
`400`	בקשה שגויה — בדוק את שדה ה-`error` לפרטים
`401`	לא מורשה — סוד סשן חסר או לא תקין
`403`	אסור — למשל, ניסיון לשנות סוכן מובנה
`404`	לא נמצא
`409`	קונפליקט — למשל, מזהה סוכן כבר קיים
`422`	שגיאת אימות — הקלט לא תואם לסכימת הכלי
`429`	חריגה ממכסת בקשות — ראה תקציבי rate-limit בסעיף האימות
`500`	שגיאת שרת — בדוק את שדה ה-`error`
`501`	לא מיושם — התכונה קיימת אך לא זמינה בדרך זו
`503`	שירות לא זמין — האחסון או הספק לא מוכנים

כל תגובות השגיאה כוללות { "error": "human-readable message" }.

דוגמת התחלה מהירה

הנה תהליך עבודה מלא: יצירת סוכן, הרצתו והזרמת התוצאות.

# 1. יצירת סוכן מותאם אישית
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": "Summarize any input concisely in 3 bullet points.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. הרצה אסינכרונית
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": "Summarize https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

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

# 3. הזרמת האירועים
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. ייצוא הסוכן לשיתוף
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.