AgenticEye Platform API

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

The machine door into the system. Everything a person does in the screens — reading every module, writing, asking in plain language, running actions and receiving events — is available here to a program.

מה זה

What this is

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

The API was built for two kinds of caller: a central brain watching every farm in the group, and a personal assistant that answers "what needs me today?" and then acts. Both use the same base URL and the same keys.

שני האחרונים פתוחים לקריאה בלי מפתח — הם מתארים את מבנה ה-API ולא מכילים נתוני לקוח, כדי שאפשר יהיה לייבא אותם לכל מסגרת סוכנים.

Those last two are readable without a key — they describe the shape of the API and hold no customer data, so any agent framework can import them.

קבלת מפתח

Get a key

בפאנל האדמין: API וגישת מוח ← מפתח חדש. בוחרים הרשאות, והמפתח מוצג פעם אחת בלבד.

In the admin panel: API & Brain access → New key. Pick scopes; the key is shown once only.

אפשר להצמיד מפתח לחוות מסוימות, להגביל בקשות לדקה (ברירת מחדל 240), לתת תאריך תפוגה ולבטל בלחיצה. כל קריאה נרשמת ביומן: מה, מתי, כמה זמן ומאיזה IP.

A key can be pinned to specific farms, rate limited (240/min by default), given an expiry and revoked in one click. Every call is audited: what, when, how long and from which IP.

הקריאה הראשונה

First call

curl -H "Authorization: Bearer $AE_KEY" https://agenticeye.com/v1/platform/me

מחזיר מי המפתח, אילו הרשאות יש לו ואילו חוות הוא רואה. אם זה עובד — הכל מחובר.

Returns who the key is, which scopes it holds and which farms it sees. If this works, everything is wired.

context — כל החווה באובייקט אחד

context — the whole farm in one object

GET /v1/platform/context?farmId=…&depth=full

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

Ready to drop straight into a prompt: farm identity, barn and flock state (age, cumulative mortality, weight against the breed standard, last log), open alerts and tasks, field reports, people, hardware and latest environment readings, medicine, and 90 days of money. Plus a narrative field — the same fact list in words that the in-app assistant is grounded in.

depth=summary מקצר את ההיסטוריה כשצריך פחות טוקנים.

depth=summary trims the history when you need fewer tokens.

insights — מה המערכת כבר יודעת

insights — what the system already knows

GET /v1/platform/insights?farmId=…
GET /v1/platform/insights?farmId=…&include=health,leaks

15 מקטעים, כל אחד מהמנוע שמפעיל את המסך המקביל במערכת — לא חישוב שני שיכול להתפצל:

15 sections, each from the engine that drives the matching screen — never a second implementation that could drift:

אם מקטע אחד נכשל הוא מחזיר {error} ושאר המקטעים ממשיכים לעבוד.

If one section fails it returns {error} and the rest keep working.

gaps — מה חסר

gaps — what is missing

GET /v1/platform/gaps?farmId=…

זו רשימת המשימות של המוח. כל פער מגיע עם kind, severity, הסבר, לרוב ids, ו-fix שאומר לאיזה endpoint לפנות: לולים בלי רישום היום, שאלות עובדים שלא נענו, התראות פתוחות מעל שלושה ימים, להקות בלי שקילה שבוע, תרופות שפג תוקפן או במלאי נמוך, חווה בלי קואורדינטות או אנשי קשר, חיבורים תקולים או שלא סונכרנו, ואין תמונות אחרונות. בנוסף בלוק dataQuality.

This is the brain's to-do list. Each gap carries kind, severity, an explanation, usually ids, and a fix naming the endpoint to call: flocks with no log today, unanswered worker questions, alerts open over three days, flocks unweighed for a week, expired or low medicine, a farm without coordinates or contacts, failing or stale integrations, and no recent photos. Plus a dataQuality block.

digest, portfolio, activity, search

digest, portfolio, activity, search

32 המשאבים

The 32 resources

כל מודול במערכת, באותה צורה בדיוק. GET /resources מחזיר את הרשימה עם השדות הניתנים לכתיבה והמסננים של כל אחד.

Every module, in exactly the same shape. GET /resources returns the list with each one's writable fields and filters.

GET    /v1/platform/{resource}
GET    /v1/platform/{resource}/{id}
POST   /v1/platform/{resource}
PATCH  /v1/platform/{resource}/{id}
DELETE /v1/platform/{resource}/{id}

כל תשובת רשימה נראית כך: { data, meta: { total, limit, offset, hasMore } }. ההרשאה לחווה נאכפת על כל שורה, גם דרך רשומת האב — רישום יומי נבדק דרך הלהקה שלו, הצעת מחיר דרך המכרז.

Every list response looks like { data, meta: { total, limit, offset, hasMore } }. Farm permission is enforced on every row, including through its parent — a daily log is checked via its flock, a bid via its tender.

סינון, חיפוש ומיון

Filtering, search and ordering

# יומן יומי של 30 הימים האחרונים, החדש קודם
GET /v1/platform/daily-logs?farmId=F&date_from=2026-08-09&order=date&dir=desc&limit=100

# התראות קריטיות פתוחות
GET /v1/platform/alerts?farmId=F&status=open&severity=critical

# חיפוש טקסט חופשי במשימות
GET /v1/platform/tasks?farmId=F&q=מים&limit=20

כתיבה

Writing

curl -X POST https://agenticeye.com/v1/platform/daily-logs \
  -H "Authorization: Bearer $AE_KEY" -H 'content-type: application/json' \
  -d '{"flockId":"…","date":"2026-09-08","mortality":12,"waterL":9800,"feedKg":4100}'

רק שדות שמופיעים ב-writableFields של המשאב נקלטים; כל היתר מתעלמים ממנו בשקט, כך ששליחת אובייקט מלא בחזרה לא יכולה לשנות מזהים או שיוך לחווה.

Only fields listed in the resource's writableFields are accepted; anything else is quietly ignored, so echoing a whole object back can never change ids or farm ownership.

שאלה בשפה חופשית

Ask in plain language

curl -X POST https://agenticeye.com/v1/platform/ask \
  -H "Authorization: Bearer $AE_KEY" -H 'content-type: application/json' \
  -d '{"farmId":"…","question":"איפה אני מפסיד הכי הרבה כסף החודש?","lang":"he"}'

התשובה מבוססת על נתוני החווה בפועל. חמש שפות נתמכות: he, en, th, es, zh. עם execute:true המודל רשאי גם לבצע פעולה — אבל רק אם למפתח יש גם actions:execute; אחרת הפעולה מוחזרת כהצעה ולא רצה.

The answer is grounded in the farm's real data. Five languages: he, en, th, es, zh. With execute:true the model may also run an action — but only if the key also holds actions:execute; otherwise the action comes back as a suppressed proposal and nothing happens.

ביצוע פעולות

Running actions

curl -X POST https://agenticeye.com/v1/platform/actions \
  -H "Authorization: Bearer $AE_KEY" -H 'content-type: application/json' \
  -d '{"farmId":"…","type":"create_task","title":"בדוק מים בלול 3","assignee":"אבי","priority":"high"}'

ללא מודל בלולאה — ולידציה דטרמיניסטית בלבד. 14 סוגים:

No model in the loop — deterministic validation only. 14 types:

כל פעולה מחזירה מתאר undo. שליחתו ל-POST /actions/undo מבטלת את הפעולה, עם סירובים מכוונים: להקה שכבר יש לה רישומים, תיק אירוע חתום, לול שיש בו להקות.

Every action returns an undo descriptor. Sending it to POST /actions/undo reverses the action, with deliberate refusals: a flock that already has logs, a sealed case file, a barn holding flocks.

Webhooks — להידחף במקום לדגום

Webhooks — be pushed, not polled

curl -X POST https://agenticeye.com/v1/platform/webhooks \
  -H "Authorization: Bearer $AE_KEY" -H 'content-type: application/json' \
  -d '{"url":"https://brain.example.com/agenticeye","events":["alert.critical","field_report.question"]}'

["*"] = הכל. כל מסירה נושאת חתימה, ואימותה הוא הדרך לדעת שההודעה באמת מאיתנו:

["*"] means everything. Every delivery carries a signature, and verifying it is how you know the message is really from us:

const expected = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(`${req.headers['x-agenticeye-timestamp']}.${rawBody}`).digest('hex');
if (expected !== req.headers['x-agenticeye-signature']) return reject();

גוף ההודעה: { id, event, orgId, farmId, createdAt, data }. hook שנכשל 20 פעמים ברצף מכובה אוטומטית.

Body: { id, event, orgId, farmId, createdAt, data }. A hook that fails 20 times in a row is switched off automatically.

גישה לכל מסלולי ה-OS

Full OS passthrough

GET /v1/platform/os/dashboard?farmId=…
GET /v1/platform/os/weekly-summary?farmId=…
GET /v1/platform/os/risk/ledger?farmId=…

/v1/platform/os/* מגיע לכל אחד מ-200+ המסלולים של האפליקציה, עם ההרשאות של המפתח. זו ההבטחה שה-API לעולם לא מפגר אחרי המסכים: קריאה דורשת read:*, כתיבה דורשת write:*.

/v1/platform/os/* reaches any of the app's 200+ endpoints with the key's permissions. This is the guarantee that the API never falls behind the screens: reading needs read:*, anything else needs write:*.

חיבור סוכן AI

Wiring an AI agent

הדרך הקצרה: לייבא את openapi.json כערכת כלים. המסמך הוא OpenAPI 3.1 עם 77 מסלולים ו-operationId ייחודי לכל פעולה, כך שרוב המסגרות ייצרו את הכלים לבד.

The short path: import openapi.json as a tool set. It is OpenAPI 3.1 with 77 paths and a unique operationId per operation, so most frameworks generate the tools themselves.

הדרך השנייה: להתחיל מ-capabilities — אובייקט JSON אחד שנכתב כדי שמודל יקרא אותו, ומתאר את המשאבים, השדות, המסננים, מסלולי התובנות, סוגי הפעולות ואירועי ה-webhook.

The other path: start from capabilities — a single JSON object written to be read by a model, describing the resources, fields, filters, intelligence endpoints, action types and webhook events.

מתכונים

Recipes

לולאה יומית של מוח

A brain's daily loop

GET  /portfolio                → איזו חווה דורשת תשומת לב
GET  /gaps?farmId=…            → מה חסר שם
GET  /insights?farmId=…        → מה המערכת כבר יודעת
POST /actions                  → לתקן

עוזרת אישית — "מה דורש אותי היום?"

Personal assistant — "what needs me today?"

const [digest, gaps] = await Promise.all([
  api(`/digest?farmId=${farm}`),
  api(`/gaps?farmId=${farm}`),
]);
const urgent = [
  ...digest.alerts.filter(a => a.severity === 'critical'),
  ...gaps.gaps.filter(g => g.severity !== 'info'),
];

הזנת נתונים ממערכת חיצונית

Feeding data from another system

POST /v1/platform/env-readings   { barnId, ts, temp, humidity, co2, nh3 }
POST /v1/platform/vision-events  { barnId, kind, value, unit, source }
POST /v1/platform/daily-logs     { flockId, date, mortality, waterL, feedKg }

שגיאות ומגבלות

Errors & limits

כל שגיאה חוזרת באותו מבנה: { "error", "message", "code"?, "requestId" }. הכותרת x-request-id מלווה כל תשובה (וגם מהדהדת מזהה ששלחתם) — שמרו אותה בלוגים שלכם.

Every error has the same shape: { "error", "message", "code"?, "requestId" }. The x-request-id header accompanies every response (and echoes one you send) — keep it in your logs.

גרסה 1.0 · capabilities · openapi.json

Version 1.0 · capabilities · openapi.json