Bots API
Bots modülünün tüm işlemleri (14) ve veri modelleri (5): adresler, izinler, girdiler, ön koşullar, olaylar ve örnekler.
Named AI coworkers: each has a job, instructions, your own Claude Code or Codex, a computer, notes and routines, and asks you before anything risky.
Modül kodu bots · 14 işlem · 5 veri modeli · 2 olay. Bir anahtar ya da token, arkasındaki kişinin bu modülde yapabildiğinden fazlasını asla yapamaz; satır düzeyindeki güvenlik uygulamadakiyle birebir aynıdır. Yetki kapsamları: bots (hepsi), bots:read (yalnız okuma) ya da bots:<yetenek>.
Kaynaklar
| Kaynak | Tablo | Listeleme ve okuma | POST | PATCH | DELETE |
|---|---|---|---|---|---|
bot_approvals | bot_approval | /api/v1/bot_approvals | |||
bot_messages | bot_message | /api/v1/bot_messages | |||
bot_routine_runs | bot_routine_run | /api/v1/bot_routine_runs | |||
bot_routines | bot_routine | /api/v1/bot_routines | |||
bots | bot | /api/v1/bots | bots.create | bots.update | bots.archive |
Listeler limit (en çok 200), cursor, order (ör. -created_at), fields ve q alır; diğer her sorgu parametresi bir sütun süzgecidir: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.
İşlemler
| İşlem | Gereken izin | Ne yapar |
|---|---|---|
bots.archive | bots:write | Archive a bot |
bots.claim_runs | bots:write | Take my due routine runs |
bots.create | bots:write | Make a bot |
bots.decide_approval | bots:write | Answer a bot’s question |
bots.delete_routine | bots:write | Delete a routine |
bots.mark_read | bots:write | Mark my chat with a bot read |
bots.post_message | bots:write | Add to my chat with a bot |
bots.report_run | bots:write | Report a routine run |
bots.request_approval | bots:write | Ask before a bot’s step |
bots.run_routine | bots:write | Run a routine now |
bots.save_routine | bots:write | Give a bot a routine |
bots.settle_approval | bots:write | Close a bot’s question |
bots.share | bots:write | Share a bot |
bots.update | bots:write | Change a bot |
bots.archive
Archive a bot — Puts a bot away (its routines stop) or brings it back. Its chats and notes stay.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bots/{id}/actions/archive- REST kısayolu:
DELETE /api/v1/bots/{id} - Asıl adres:
POST /api/v1/actions/bots.archive
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Doldurulduğu yer: adresteki {id} · Bot · kimliği: bot |
archived | boolean | Arşivlendi · false brings it back. |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot must be one you can see. |
not_your_bot | Only the member who made a bot archives it. |
bot_working | A bot that is working right now is stopped first. |
name_taken | A bot brought back may not share a name with a live one. |
Neye yazar: bot (update) — Archives or restores the bot; bot_routine (update) — An archived bot’s routines stop; bot_routine_run (update) — Its waiting runs are skipped
curl -X POST https://app.getera.io/api/v1/bots/BOT_ID/actions/archive \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"archived":true}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.bots.archive("BOT_ID", {
archived: true
})era bots archive BOT_ID \
--archived true{
"name": "era__bots__archive",
"arguments": {
"id": "BOT_ID",
"archived": true
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found, not_your_bot, bot_working, name_taken · 429 çok sık istek
bots.claim_runs
Take my due routine runs — Your own desktop takes your routine runs that are due, to work them on the bots’ computers with your subscription.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_routine_runs/actions/claim_runs- Asıl adres:
POST /api/v1/actions/bots.claim_runs
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
deviceId | uuid | Masaüstü | |
limit | number | En fazla · en az 1 · en çok 5 |
Neye yazar: bot_routine_run (update) — Marks the runs taken by this desktop
curl -X POST https://app.getera.io/api/v1/bot_routine_runs/actions/claim_runs \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"deviceId":"DEVICE_ID"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botRoutineRuns.claimRuns({
deviceId: "DEVICE_ID"
})era bot_routine_runs claim_runs \
--device-id "DEVICE_ID"{
"name": "era__bots__claim_runs",
"arguments": {
"deviceId": "DEVICE_ID"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 429 çok sık istek
bots.create
Make a bot — A named coworker with a job, instructions, your own engine and a computer. It acts only with your permissions.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bots/actions/create- REST kısayolu:
POST /api/v1/bots - Asıl adres:
POST /api/v1/actions/bots.create
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
name | string | evet | Ad · en çok 80 |
role | string | İş · One line under its name: “Follows up quotes”. · en çok 160 | |
avatar | object / array | Profil görseli · { kind: initial | emoji | image, value? } — an image is a data: URL ≤ 200 KB. | |
color | string (enum) | Renk · İzin verilen değerler: blue, green, orange, red, teal, slate, amber, emerald, sky, rose | |
instructions | string | Talimatlar · en çok 20000 | |
provider | string (enum) | Motor · İzin verilen değerler: claude, codex | |
model | string | Model · en çok 120 | |
computer | string (enum) | Bilgisayar · İzin verilen değerler: this_pc, cloud | |
computerMachineId | uuid | Bulut bilgisayar | |
allowedApps | object / array | Only these apps · ["Chrome", "Excel"] — empty = any app (the denylist and the floor still apply). | |
eraData | boolean | May use Era data (your permissions) | |
approvalMode | string (enum) | Asks before · İzin verilen değerler: ask, risky, auto | |
memoryEnabled | boolean | Keeps notes | |
visibility | string (enum) | Kim görür · İzin verilen değerler: private, workspace |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
name_required | A bot needs a name. |
name_taken | Your live bots have different names. |
bad_engine | The engine is Claude Code or Codex. |
bad_computer | The computer is this PC or your cloud computer. |
machine_not_yours | A bot uses only your own cloud computer. |
bad_approval_mode | Approval mode is ask, risky or auto. |
bad_color | The colour is one of Era’s section colours (never purple). |
bad_visibility | A bot is private or shared with the workspace. |
bad_avatar | An avatar is an initial, an emoji or a small picture. |
bad_apps | Allowed apps is a short list of names. |
too_many_bots | A member keeps at most fifty live bots. |
Neye yazar: bot (insert) — Adds the bot, owned by you
curl -X POST https://app.getera.io/api/v1/bots/actions/create \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Name"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.bots.create({
name: "Name"
})era bots create \
--name "Name"{
"name": "era__bots__create",
"arguments": {
"name": "Name"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 name_required, name_taken, bad_engine, bad_computer, machine_not_yours, bad_approval_mode, bad_color, bad_visibility, bad_avatar, bad_apps, too_many_bots · 429 çok sık istek
bots.decide_approval
Answer a bot’s question — Allow or deny the step a bot is waiting on — from the desktop, the web, the phone or the API. Denied, the step never runs.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_approvals/{id}/actions/decide_approval- Asıl adres:
POST /api/v1/actions/bots.decide_approval
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Doldurulduğu yer: adresteki {id} · Soru · kimliği: bot_approval |
decision | string (enum) | evet | Yanıt · İzin verilen değerler: allow, deny |
via | string (enum) | Nereden · İzin verilen değerler: desktop, web, phone, api |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bad_decision | The answer is allow or deny. |
approval_not_found | Only the member whose bot asked answers it. |
approval_closed | A question is answered once, before it expires. |
Yayımladığı olaylar: bots.approval_decided
Neye yazar: bot_approval (update) — Records your answer; bot_routine_run (update) — A waiting routine run goes on
curl -X POST https://app.getera.io/api/v1/bot_approvals/BOT_APPROVAL_ID/actions/decide_approval \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"decision":"allow"}'{
"ok": true,
"result": "…",
"events": [
"bots.approval_decided"
]
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botApprovals.decideApproval("BOT_APPROVAL_ID", {
decision: "allow"
})era bot_approvals decide_approval BOT_APPROVAL_ID \
--decision "allow"{
"name": "era__bots__decide_approval",
"arguments": {
"id": "BOT_APPROVAL_ID",
"decision": "allow"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bad_decision, approval_not_found, approval_closed · 429 çok sık istek
bots.delete_routine
Delete a routine — Removes a bot’s routine and its run history. Its reports stay in your chat.
Gereken izin bots:write · siler ya da geri alınamaz
https://app.getera.io/api/v1/bot_routines/{id}/actions/delete_routine- Asıl adres:
POST /api/v1/actions/bots.delete_routine
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Doldurulduğu yer: adresteki {id} · Routine · kimliği: bot_routine |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
routine_not_found | The routine must be one of yours. |
Neye yazar: bot_routine (delete) — Removes the routine; bot_routine_run (delete) — Its runs go with it, by cascade
curl -X POST https://app.getera.io/api/v1/bot_routines/BOT_ROUTINE_ID/actions/delete_routine \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botRoutines.deleteRoutine("BOT_ROUTINE_ID")era bot_routines delete_routine BOT_ROUTINE_ID{
"name": "era__bots__delete_routine",
"arguments": {
"id": "BOT_ROUTINE_ID"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 routine_not_found · 429 çok sık istek
bots.mark_read
Mark my chat with a bot read — Clears the unread count of your chat with a bot.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_messages/actions/mark_read- Asıl adres:
POST /api/v1/actions/bots.mark_read
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
botId | uuid | evet | Bot |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot id is a bot id. |
Neye yazar: bot_message (update) — Stamps your unread messages read
curl -X POST https://app.getera.io/api/v1/bot_messages/actions/mark_read \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"botId":"BOT_ID"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botMessages.markRead({
botId: "BOT_ID"
})era bot_messages mark_read \
--bot-id "BOT_ID"{
"name": "era__bots__mark_read",
"arguments": {
"botId": "BOT_ID"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found · 429 çok sık istek
bots.post_message
Add to my chat with a bot — Your message to a bot, or its answer as your own desktop reports it. Your chat with a bot is yours alone.
Gereken izin bots:write · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır)
https://app.getera.io/api/v1/bot_messages/actions/post_message- Asıl adres:
POST /api/v1/actions/bots.post_message
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
botId | uuid | evet | Bot · kimliği: bot |
role | string (enum) | Nereden · İzin verilen değerler: user, bot, system | |
kind | string (enum) | Tür · İzin verilen değerler: text, report, approval, routine, error | |
text | string | evet | Metin · en çok 60000 |
runRef | string | Desktop run · en çok 100 | |
routineId | uuid | Routine | |
approvalId | uuid | Onay | |
clientRef | string | Same-message key · en çok 100 |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot must be one you can see. |
bot_archived | An archived bot takes no messages. |
bad_message | A message has words, a known sender and a known kind. |
Neye yazar: bot_message (insert) — Adds the message to your chat with the bot
curl -X POST https://app.getera.io/api/v1/bot_messages/actions/post_message \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"botId":"BOT_ID","text":"Text"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botMessages.postMessage({
botId: "BOT_ID",
text: "Text"
})era bot_messages post_message \
--bot-id "BOT_ID" \
--text "Text"{
"name": "era__bots__post_message",
"arguments": {
"botId": "BOT_ID",
"text": "Text"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found, bot_archived, bad_message · 429 çok sık istek
bots.report_run
Report a routine run — Your desktop says a run started, waits for you, finished or failed; a finished run’s result lands in your chat with the bot.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_routine_runs/{id}/actions/report_run- Asıl adres:
POST /api/v1/actions/bots.report_run
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Doldurulduğu yer: adresteki {id} · Çalıştır · kimliği: bot_routine_run |
state | string (enum) | evet | Durum · İzin verilen değerler: running, waiting, completed, failed |
runRef | string | Desktop run · en çok 100 | |
result | string | Sonuç · en çok 20000 | |
error | string | Hata · en çok 4000 |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bad_run_state | A run is running, waiting, completed or failed. |
run_not_found | The run must be one of yours, taken and not ended. |
Neye yazar: bot_routine_run (update) — Moves the run on; bot_routine (update) — Stamps when it last ran; bot_message (insert) — Puts the result in your chat with the bot
curl -X POST https://app.getera.io/api/v1/bot_routine_runs/BOT_ROUTINE_RUN_ID/actions/report_run \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"state":"running"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botRoutineRuns.reportRun("BOT_ROUTINE_RUN_ID", {
state: "running"
})era bot_routine_runs report_run BOT_ROUTINE_RUN_ID \
--state "running"{
"name": "era__bots__report_run",
"arguments": {
"id": "BOT_ROUTINE_RUN_ID",
"state": "running"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bad_run_state, run_not_found · 429 çok sık istek
bots.request_approval
Ask before a bot’s step — A bot working for you stops before a risky step and asks; nothing runs until you allow it. In your quiet hours the question waits silently.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_approvals/actions/request_approval- Asıl adres:
POST /api/v1/actions/bots.request_approval
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
botId | uuid | evet | Bot · kimliği: bot |
requestRef | string | evet | The engine’s id for the question · en çok 200 |
summary | string | evet | What will happen · en çok 1000 |
tool | string | Araç · en çok 200 | |
kind | string | Tür · screen · command · file_write · network · payment · send · delete · credentials · install · other · en çok 31 | |
risk | string (enum) | Risk · İzin verilen değerler: step, risky, floor | |
detail | object / array | Ayrıntı | |
runRef | string | Desktop run · en çok 100 | |
runId | uuid | Routine run | |
expiresInMinutes | number | Waits for (minutes) · en az 1 · en çok 1440 |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot must be one you can see. |
bad_approval | A question has a summary, the engine’s id and a known risk. |
Yayımladığı olaylar: bots.approval_requested
Neye yazar: bot_approval (insert) — Records the question, for you only; bot_routine_run (update) — A routine run waits for you
curl -X POST https://app.getera.io/api/v1/bot_approvals/actions/request_approval \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"botId":"BOT_ID","requestRef":"The engine’s id for the question","summary":"What will happen"}'{
"ok": true,
"result": "…",
"events": [
"bots.approval_requested"
]
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botApprovals.requestApproval({
botId: "BOT_ID",
requestRef: "The engine’s id for the question",
summary: "What will happen"
})era bot_approvals request_approval \
--bot-id "BOT_ID" \
--request-ref "The engine’s id for the question" \
--summary "What will happen"{
"name": "era__bots__request_approval",
"arguments": {
"botId": "BOT_ID",
"requestRef": "The engine’s id for the question",
"summary": "What will happen"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found, bad_approval · 429 çok sık istek
bots.run_routine
Run a routine now — Queues one run of the routine for your desktop to start now (quiet hours do not hold a run you asked for).
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_routine_runs/actions/run_routine- Asıl adres:
POST /api/v1/actions/bots.run_routine
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Routine · kimliği: bot_routine |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
routine_not_found | The routine must be one of yours. |
bot_archived | An archived bot runs nothing. |
routine_busy | One run of a routine at a time. |
Neye yazar: bot_routine_run (insert) — Queues the run
curl -X POST https://app.getera.io/api/v1/bot_routine_runs/actions/run_routine \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"id":"BOT_ROUTINE_ID"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botRoutineRuns.runRoutine({
id: "BOT_ROUTINE_ID"
})era bot_routine_runs run_routine \
--id "BOT_ROUTINE_ID"{
"name": "era__bots__run_routine",
"arguments": {
"id": "BOT_ROUTINE_ID"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 routine_not_found, bot_archived, routine_busy · 429 çok sık istek
bots.save_routine
Give a bot a routine — A task your bot does on a schedule (daily, weekdays, weekly, every N minutes, once, cron) — on Era’s scheduler, reported into your chat with it.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_routines/actions/save_routine- Asıl adres:
POST /api/v1/actions/bots.save_routine
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | Routine · Absent = a new routine. | |
botId | uuid | evet | Bot · kimliği: bot |
name | string | evet | Ad · en çok 120 |
prompt | string | evet | What to do each time · en çok 20000 |
schedule | object / array | evet | Ne zaman · { kind: daily|weekdays|weekly|interval|once|cron|manual, time?: "09:00", days?: [1,3], everyMinutes?: 60, at?: ISO, cron?: "0 9 * * 1-5", timezone } |
enabled | boolean | Açık | |
respectQuietHours | boolean | Wait out my quiet hours |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot must be one you can see. |
not_your_bot | Only the bot’s owner gives it routines. |
bot_archived | An archived bot takes no routines. |
routine_incomplete | A routine has a name and a task. |
bad_schedule | A schedule is one of the kinds, with a real time, days, interval (≥ 15 min), date or cron, in a real time zone. |
routine_not_found | The routine must be one of yours, on this bot. |
too_many_routines | A bot keeps at most twenty routines. |
Neye yazar: bot_routine (upsert) — Writes the routine and its next run
curl -X POST https://app.getera.io/api/v1/bot_routines/actions/save_routine \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"botId":"BOT_ID","name":"Name","prompt":"What to do each time","schedule":{}}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botRoutines.saveRoutine({
botId: "BOT_ID",
name: "Name",
prompt: "What to do each time",
schedule: {}
})era bot_routines save_routine --data '{"botId":"BOT_ID","name":"Name","prompt":"What to do each time","schedule":{}}'{
"name": "era__bots__save_routine",
"arguments": {
"botId": "BOT_ID",
"name": "Name",
"prompt": "What to do each time",
"schedule": {}
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found, not_your_bot, bot_archived, routine_incomplete, bad_schedule, routine_not_found, too_many_routines · 429 çok sık istek
bots.settle_approval
Close a bot’s question — The desktop says a question is no longer needed (the run ended or you answered on the card) or that its notification was shown.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bot_approvals/{id}/actions/settle_approval- Asıl adres:
POST /api/v1/actions/bots.settle_approval
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | Doldurulduğu yer: adresteki {id} · Soru · kimliği: bot_approval | |
requestRef | string | The engine’s id for it · en çok 200 | |
status | string (enum) | Şimdi · İzin verilen değerler: cancelled, expired | |
notified | boolean | Its notification was shown |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bad_decision | A question that is no longer needed is cancelled or expired. |
approval_not_found | The question must be one of yours. |
Neye yazar: bot_approval (update) — Closes the question or stamps its notification
curl -X POST https://app.getera.io/api/v1/bot_approvals/BOT_APPROVAL_ID/actions/settle_approval \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"requestRef":"The engine’s id for it"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.botApprovals.settleApproval("BOT_APPROVAL_ID", {
requestRef: "The engine’s id for it"
})era bot_approvals settle_approval BOT_APPROVAL_ID \
--request-ref "The engine’s id for it"{
"name": "era__bots__settle_approval",
"arguments": {
"id": "BOT_APPROVAL_ID",
"requestRef": "The engine’s id for it"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bad_decision, approval_not_found · 429 çok sık istek
bots.share
Share a bot — Shared, every member sees the bot and can talk to it — as themselves, on their own subscription and permissions. Only you change it or use its computer.
Gereken izin bots:write · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır)
https://app.getera.io/api/v1/bots/{id}/actions/share- Asıl adres:
POST /api/v1/actions/bots.share
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Doldurulduğu yer: adresteki {id} · Bot · kimliği: bot |
visibility | string (enum) | evet | Kim görür · İzin verilen değerler: private, workspace |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot must be one you can see. |
not_your_bot | Only the member who made a bot shares it. |
bad_visibility | A bot is private or shared with the workspace. |
Neye yazar: bot (update) — Changes who sees the bot
curl -X POST https://app.getera.io/api/v1/bots/BOT_ID/actions/share \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"visibility":"private"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.bots.share("BOT_ID", {
visibility: "private"
})era bots share BOT_ID \
--visibility "private"{
"name": "era__bots__share",
"arguments": {
"id": "BOT_ID",
"visibility": "private"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found, not_your_bot, bad_visibility · 429 çok sık istek
bots.update
Change a bot — Its name, job, instructions, engine, computer, apps, Era data access or approval mode. A run already working keeps its old settings.
Gereken izin bots:write · veriyi değiştirir
https://app.getera.io/api/v1/bots/{id}/actions/update- REST kısayolu:
PATCH /api/v1/bots/{id} - Asıl adres:
POST /api/v1/actions/bots.update
Girdi
| Alan | Tür | Zorunlu | Açıklama |
|---|---|---|---|
id | uuid | evet | Doldurulduğu yer: adresteki {id} · Bot · kimliği: bot |
name | string | Ad · en çok 80 | |
role | string | İş · One line under its name: “Follows up quotes”. · en çok 160 | |
avatar | object / array | Profil görseli · { kind: initial | emoji | image, value? } — an image is a data: URL ≤ 200 KB. | |
color | string (enum) | Renk · İzin verilen değerler: blue, green, orange, red, teal, slate, amber, emerald, sky, rose | |
instructions | string | Talimatlar · en çok 20000 | |
provider | string (enum) | Motor · İzin verilen değerler: claude, codex | |
model | string | Model · en çok 120 | |
computer | string (enum) | Bilgisayar · İzin verilen değerler: this_pc, cloud | |
computerMachineId | uuid | Bulut bilgisayar | |
allowedApps | object / array | Only these apps · ["Chrome", "Excel"] — empty = any app (the denylist and the floor still apply). | |
eraData | boolean | May use Era data (your permissions) | |
approvalMode | string (enum) | Asks before · İzin verilen değerler: ask, risky, auto | |
memoryEnabled | boolean | Keeps notes |
Ön koşullar
Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:
| Kod | Ne zaman reddedilir |
|---|---|
bot_not_found | The bot must be one you can see. |
not_your_bot | Only the member who made a bot changes it, even when it is shared. |
name_required | A bot needs a name. |
name_taken | Your live bots have different names. |
bad_engine | The engine is Claude Code or Codex. |
bad_computer | The computer is this PC or your cloud computer. |
machine_not_yours | A bot uses only your own cloud computer. |
bad_approval_mode | Approval mode is ask, risky or auto. |
bad_color | The colour is one of Era’s section colours. |
bad_avatar | An avatar is an initial, an emoji or a small picture. |
bad_apps | Allowed apps is a short list of names. |
Neye yazar: bot (update) — Rewrites the bot
curl -X POST https://app.getera.io/api/v1/bots/BOT_ID/actions/update \
-H "Authorization: Bearer $ERA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"name":"Name"}'{
"ok": true,
"result": "…",
"events": []
}import { createEra } from "@getera/sdk"
const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.bots.update("BOT_ID", {
name: "Name"
})era bots update BOT_ID \
--name "Name"{
"name": "era__bots__update",
"arguments": {
"id": "BOT_ID",
"name": "Name"
}
}Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde bots:write izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bot_not_found, not_your_bot, name_required, name_taken, bad_engine, bad_computer, machine_not_yours, bad_approval_mode, bad_color, bad_avatar, bad_apps · 429 çok sık istek
Veri modelleri
BotApproval
Tablo bot_approval · Kaynak bot_approvals
GET /api/v1/bot_approvalsGET /api/v1/bot_approvals/{id}
| Sütun | Tür | Boş olabilir | İzin verilen değerler | Bağlı olduğu tablo |
|---|---|---|---|---|
id | string (uuid) · uuid | |||
organization_id | string (uuid) · uuid | organization | ||
workspace_id | string (uuid) · uuid | workspace | ||
user_id | string (uuid) · uuid | app_user | ||
bot_id | string (uuid) · uuid | bot | ||
run_id | string (uuid) · uuid | evet | bot_routine_run | |
run_ref | string · text | evet | ||
request_ref | string · text | |||
tool | string · text | |||
kind | string · text | |||
summary | string · text | |||
detail | object · jsonb | |||
risk | string · text | step, risky, floor | ||
status | string · text | pending, allowed, denied, expired, cancelled | ||
decided_at | string (date-time) · timestamptz | evet | ||
decided_via | string · text | evet | ||
notify_after | string (date-time) · timestamptz | evet | ||
notified_at | string (date-time) · timestamptz | evet | ||
expires_at | string (date-time) · timestamptz | |||
created_at | string (date-time) · timestamptz | |||
updated_at | string (date-time) · timestamptz |
Birincil anahtar: id
Tekil: workspace_id, user_id, request_ref
Denetimler:
CHECK (((decided_via IS NULL) OR (decided_via ~ '^[a-z]{2,12}$'::text)))CHECK (((jsonb_typeof(detail) = 'object'::text) AND (length((detail)::text) <= 20000)))CHECK ((kind ~ '^[a-z][a-z_]{0,30}$'::text))CHECK (((length(request_ref) >= 1) AND (length(request_ref) <= 200)))CHECK (((run_ref IS NULL) OR (length(run_ref) <= 100)))CHECK (((length(btrim(summary)) >= 1) AND (length(btrim(summary)) <= 1000)))CHECK (((length(tool) >= 1) AND (length(tool) <= 200)))
BotMessage
Tablo bot_message · Kaynak bot_messages
GET /api/v1/bot_messagesGET /api/v1/bot_messages/{id}
| Sütun | Tür | Boş olabilir | İzin verilen değerler | Bağlı olduğu tablo |
|---|---|---|---|---|
id | string (uuid) · uuid | |||
organization_id | string (uuid) · uuid | organization | ||
workspace_id | string (uuid) · uuid | workspace | ||
user_id | string (uuid) · uuid | app_user | ||
bot_id | string (uuid) · uuid | bot | ||
role | string · text | user, bot, system | ||
kind | string · text | text, report, approval, routine, error | ||
text | string · text | |||
run_ref | string · text | evet | ||
routine_id | string (uuid) · uuid | evet | bot_routine | |
approval_id | string (uuid) · uuid | evet | ||
client_ref | string · text | evet | ||
read_at | string (date-time) · timestamptz | evet | ||
created_at | string (date-time) · timestamptz |
Birincil anahtar: id
Denetimler:
CHECK (((client_ref IS NULL) OR (length(client_ref) <= 100)))CHECK (((run_ref IS NULL) OR (length(run_ref) <= 100)))CHECK ((length(text) <= 60000))
BotRoutineRun
Tablo bot_routine_run · Kaynak bot_routine_runs
GET /api/v1/bot_routine_runsGET /api/v1/bot_routine_runs/{id}
| Sütun | Tür | Boş olabilir | İzin verilen değerler | Bağlı olduğu tablo |
|---|---|---|---|---|
id | string (uuid) · uuid | |||
organization_id | string (uuid) · uuid | organization | ||
workspace_id | string (uuid) · uuid | workspace | ||
user_id | string (uuid) · uuid | app_user | ||
routine_id | string (uuid) · uuid | bot_routine | ||
bot_id | string (uuid) · uuid | bot | ||
trigger | string · text | schedule, manual | ||
state | string · text | queued, held, claimed, running, waiting, completed, failed, missed, skipped | ||
scheduled_for | string (date-time) · timestamptz | evet | ||
not_before | string (date-time) · timestamptz | evet | ||
prompt | string · text | evet | ||
run_ref | string · text | evet | ||
device_id | string (uuid) · uuid | evet | ||
result | string · text | evet | ||
error | string · text | evet | ||
claimed_at | string (date-time) · timestamptz | evet | ||
started_at | string (date-time) · timestamptz | evet | ||
finished_at | string (date-time) · timestamptz | evet | ||
created_at | string (date-time) · timestamptz | |||
updated_at | string (date-time) · timestamptz |
Birincil anahtar: id
Denetimler:
CHECK (((error IS NULL) OR (length(error) <= 4000)))CHECK (((prompt IS NULL) OR (length(prompt) <= 20000)))CHECK (((result IS NULL) OR (length(result) <= 20000)))CHECK (((run_ref IS NULL) OR (length(run_ref) <= 100)))
BotRoutine
Tablo bot_routine · Kaynak bot_routines
GET /api/v1/bot_routinesGET /api/v1/bot_routines/{id}
| Sütun | Tür | Boş olabilir | İzin verilen değerler | Bağlı olduğu tablo |
|---|---|---|---|---|
id | string (uuid) · uuid | |||
organization_id | string (uuid) · uuid | organization | ||
workspace_id | string (uuid) · uuid | workspace | ||
user_id | string (uuid) · uuid | app_user | ||
bot_id | string (uuid) · uuid | bot | ||
name | string · text | |||
prompt | string · text | |||
schedule_kind | string · text | daily, weekdays, weekly, interval, once, cron, manual | ||
schedule_spec | object · jsonb | |||
timezone | string · text | |||
enabled | boolean · bool | |||
paused_reason | string · text | evet | ||
respect_quiet_hours | boolean · bool | |||
catch_up_minutes | integer · int2 | |||
next_run_at | string (date-time) · timestamptz | evet | ||
last_run_at | string (date-time) · timestamptz | evet | ||
created_at | string (date-time) · timestamptz | |||
updated_at | string (date-time) · timestamptz |
Birincil anahtar: id
Denetimler:
CHECK (((catch_up_minutes >= 0) AND (catch_up_minutes <= 1440)))CHECK (((length(btrim(name)) >= 1) AND (length(btrim(name)) <= 120)))CHECK (((paused_reason IS NULL) OR (length(paused_reason) <= 500)))CHECK (((length(btrim(prompt)) >= 1) AND (length(btrim(prompt)) <= 20000)))CHECK ((jsonb_typeof(schedule_spec) = 'object'::text))CHECK (((length(timezone) >= 1) AND (length(timezone) <= 64)))
Bot
Tablo bot · Kaynak bots
GET /api/v1/botsGET /api/v1/bots/{id}POST /api/v1/bots→bots.createPATCH /api/v1/bots/{id}→bots.updateDELETE /api/v1/bots/{id}→bots.archive
| Sütun | Tür | Boş olabilir | İzin verilen değerler | Bağlı olduğu tablo |
|---|---|---|---|---|
id | string (uuid) · uuid | |||
organization_id | string (uuid) · uuid | organization | ||
workspace_id | string (uuid) · uuid | workspace | ||
owner_user_id | string (uuid) · uuid | app_user | ||
name | string · text | |||
role | string · text | |||
avatar | object · jsonb | |||
color | string · text | |||
instructions | string · text | |||
provider | string · text | claude, codex | ||
model | string · text | evet | ||
computer | string · text | this_pc, cloud | ||
computer_machine_id | string (uuid) · uuid | evet | computer_machine | |
allowed_apps | string[] · text[] | |||
era_data | boolean · bool | |||
approval_mode | string · text | ask, risky, auto | ||
memory_enabled | boolean · bool | |||
status | string · text | active, archived | ||
visibility | string · text | private, workspace | ||
archived_at | string (date-time) · timestamptz | evet | ||
created_at | string (date-time) · timestamptz | |||
updated_at | string (date-time) · timestamptz |
Birincil anahtar: id
Denetimler:
CHECK ((cardinality(allowed_apps) <= 40))CHECK (((jsonb_typeof(avatar) = 'object'::text) AND (length((avatar)::text) <= 280000)))CHECK (((color ~ '^[a-z]{3,12}$'::text) AND (color <> ALL (ARRAY['purple'::text, 'violet'::text]))))CHECK ((length(instructions) <= 20000))CHECK (((model IS NULL) OR ((length(model) >= 1) AND (length(model) <= 120))))CHECK (((length(btrim(name)) >= 1) AND (length(btrim(name)) <= 80)))CHECK ((length(role) <= 160))
Olaylar
İş akışları ve webhook'lar bu olaylara tepki verir.
| Olay | Ne olur | Taşıdığı alanlar |
|---|---|---|
bots.approval_decided | You allowed or denied a bot’s step. | id, botId, status |
bots.approval_requested | A bot working for you waits for your OK before a step. | id, botId, summary, risk, recipientUserId |