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

API ציבורי

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

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

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

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

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

עבור האפליקציה המקומית (אוטומטי): אפליקציית Caiioo למחשב, תוספי הדפדפן והאפליקציות לנייד מזדהים אוטומטית דרך כותרת ה-auth הקיימת (X-Relay-Auth). אין צורך בהגדרה ידנית — האפליקציה מטפלת בזה מאחורי הקלעים.

הגדרה:

  1. פתח את הגדרות Caiioo > גישת API
  2. העבר את Enable Public API למצב פעיל
  3. הגדר API access token (כל מחרוזת שתבחר — התייחס אליה כאל סיסמה)
  4. השתמש ב-token הזה בכל בקשות ה-API

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

ספקים ומודלים

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

רשימת ספקים:

GET /v1/providers

מחזיר את כל סוגי הספקים המוגדרים (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten, ואחרים ככל שיתווספו) עם דגלי יכולות (supportsVision, supportsToolCalling, supportsStreaming וכו') והאם מוגדר מפתח API.

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

GET /v1/providers/anthropic/models

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

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

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)

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

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

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

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

{
  "agentId": "general",
  "input": { "message": "מה מזג האוויר בפריז היום?" },
  "mode": "sync"
}

מחזיר 200 עם { content, usage, status: "completed" } לאחר שהסוכן מסיים. אם חלה שגיאה בסוכן, מחזיר 500 עם { error, status: "error" }.

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

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

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

{
  "agentId": "my-research-agent",
  "input": { "message": "כתוב ניתוח של 2000 מילים על מגמות באנרגיה מתחדשת" },
  "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, קריאות לכלים, פעילות סוכני-משנה, ואירוע הסיום (GENERATION_COMPLETE, GENERATION_ERROR, או GENERATION_CANCELLED). הזרם מסתיים לאחר אירוע הסיום.

ביטול הרצה:

POST /v1/runs/{runId}/cancel

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

Threads

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

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

GET /v1/threads

מחזיר threads עבור הפרופיל הנוכחי כאשר ה-messages הוסרו לצורך ביצועים. כל thread כולל id, title, createdAt, updatedAt, modeId, archived, וסטטיסטיקות שימוש.

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

GET /v1/threads/{id}

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

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

GET /v1/threads/{id}/messages

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

יצירת thread:

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

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

מחזיר 201 עם ה-thread החדש. כברירת מחדל, ה-API אינו מחליף את ה-thread הפעיל באפליקציה — העבר "setActive": true ב-body אם ברצונך לבצע זאת. ה-thread החדש יופיע בסרגל הצד באופן מיידי (באמצעות שידור WebSocket).

עדכון thread:

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

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

שדות ניתנים לעדכון: title, modeId, archived, lastUsedModel. שינויים משודרים לסרגל הצד בזמן אמת.

מחיקת 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 מוגנים (שנשמרו באמצעות מתג שמירת הנתונים - data retention) מוחרגים מריקון האשפה.

המשך שיחה באמצעות ה-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) שלך — השרתים המעניקים לסוכנים גישה לכלים חיצוניים ולמקורות נתונים.

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

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

עדכון שרת:

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

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

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

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

{ "enabled": false }

מחיקת שרת:

DELETE /v1/mcp-servers/{id}

ניהול תהליכים

עבור שרתי 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 של הכלים.

כלים וערכות כלים

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

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

GET /v1/toolkits

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

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

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

קבלת פרטי כלי עם סכימת קלט:

GET /v1/tools/calculator

מחזיר את ה-JSON Schema של הכלי עבור פרמטרי הקלט שלו, כך שתוכל לבצע אימות לפני ההפעלה.

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

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

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

מחזיר { result }. הקלט מאומת מול סכימת הכלי — קלט לא תקין יחזיר 422 עם פרטים. כלי MCP מרוחקים יחזירו 501 עם הנחיה להשתמש ב-/v1/runs במקום זאת (הם דורשים את תעבורת תת-תהליך הסוכן).

מחברים (Connectors)

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

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

GET /v1/connectors/catalog

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

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

GET /v1/connectors

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

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

POST /v1/connectors/{id}/test

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

הסרת חיבור:

DELETE /v1/connectors/{id}

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

טריגרים

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

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

GET /v1/triggers

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

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}} בהנחיית הטריגר יוחלף בגוף הבקשה הגולמי.

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

צור כלים משלך שסוכנים יכולים לקרוא להם. פונקציות נכתבות ב-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}

תהליכי עבודה (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 שגיאת אימות — הקלט אינו תואם לסכימת הכלי
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.