Beyin API başvurusu

Era Beyin’in her uç noktası ve MCP aracı: adres, kapsam, parametreler, yanıtlar, SDK, CLI ve hatalar — Beyin API’sinin kendi tanımından üretilir.

Aşağıdaki her uç nokta Era’nın çekirdeğinde bir kez tanımlanır; sunucu, OpenAPI belgesi (/api/v1/openapi.json içinde brain etiketi), SDK’lar, CLI ve bu sayfa hep o tanımdan üretilir. Bir API anahtarıyla (Authorization: Bearer era_…) ya da bir OAuth erişim belirteciyle kimlik doğrula. Bir kimlik bilgisi, arkasındaki kişinin Era uygulamasında gördüğünden fazlasını asla görmez.

Kapsamlar

ScopeNe yapar
brainHafızaları okur ve yazar (kişinin Beyin’de yapabildiği her şey).
brain:readArama, çizge, liste, getirme, açıklama, kaynaklar, işleme durumu.
brain:writeAyrıca ekleme, düzeltme ve unutma. brain:read içerir.
*, ai, ai:read, ai:writeBeyin’e de erişir (Beyin ai modülüne aittir).

Yalnızca hafızaya erişen bir kimlik bilgisi, hiçbir modüle ait olmayan hafızaları görür. Bir modülden (CRM, finans …) türeyen bilgiler, kimlik bilgisi o modülü de okuyabiliyorsa hatırlanır — CRM’den türeyen bilgileri hatırlamak için anahtara ya da belirtece crm:read ekle.

Uç noktalar

AdresGerekirNe yapar
POST/api/v1/brain/memoriesbrain:writeHafıza ekle
GET/api/v1/brain/jobs/{id}brain:readİşleme durumu
POST/api/v1/brain/searchbrain:readHafızada ara
GET/api/v1/brain/memoriesbrain:readHafızaları listele
GET/api/v1/brain/memories/{id}brain:readBir hafızayı getir
PATCH/api/v1/brain/memories/{id}brain:writeBir hafızayı düzelt
DELETE/api/v1/brain/memories/{id}brain:writeBir hafızayı unut
GET/api/v1/brain/entitiesbrain:readVarlıkları listele
GET/api/v1/brain/entities/{id}brain:readBir varlık ve komşuları
GET/api/v1/brain/graphbrain:readBir soru için çizge yolları
GET/api/v1/brain/pathsbrain:readİki varlık arasındaki yol
GET/api/v1/brain/sourcesbrain:readKaynaklar
POST/api/v1/brain/explainbrain:readBir sonucu açıkla

Her hata tek biçimdedir: { "error": { "code", "message", "status", "problems"?, "request_id" } }. Olmayan bir kayıt ile görmeye yetkin olmayan bir kayıt aynı 404’ü verir; kimlikler yoklanamaz.

Hafıza ekle

Beyin’e hatırlanacak bir şey ver: serbest metin, bir konuşma, hazır bilgiler ya da bir kayıt. Era’nın işleme çalışanı kendi başına anlamlı bilgiler çıkarır, adı geçen kişi, şirket ve ürünleri bağlar, bildikleriyle karşılaştırır (en yeni değer kazanır) ve yerel olarak gömer. text, messages, facts ya da record alanlarından tam olarak birini gönder. Saklanan hafızaları aynı çağrıda geri almak için wait (saniye) ver.

POSThttps://app.getera.io/api/v1/brain/memories
API anahtarı ya da OAuth belirteci · brain:write

Gövde

AlanTürZorunluNotlar
textstringSerbest metin: bir not, bir e-posta, bir döküm. 20–24 000 karakter. · min 20 · max 24000
messagesarray of objectBir konuşma; her mesaj konuşanıyla saklanır. · ≤ 200 items
factsarray of objectHazır bilgiler: verildiği gibi saklanır (çıkarım yok). · ≤ 40 items
recordobjectYapılandırılmış bir kayıt (kendi sisteminden bir talep, kişi ya da sipariş).
sourceobjectNereden geldiği. Hatırlanan her bilgiyle gösterilir. Varsayılan: çağıranın notu.
visibilityworkspace · privateprivate: yalnızca sen hatırlarsın. · default "workspace"
modulestringYalnızca okuyabildiğin bir modülün okuyucularına açık tut (ör. crm). · max 64
waitintegerHafızaların saklanmasını kaç saniye bekleyeceği (0 = hemen dön). · default 0 · ≥ 0 · ≤ 20

Örnek

curl -X POST "https://app.getera.io/api/v1/brain/memories" \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Ada Lovelace from Analytical Engines Ltd prefers invoices in EUR, sent on the 1st of each month.","source":{"kind":"note","label":"Call notes"},"wait":10}'
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.add({ text: 'Ada Lovelace prefers invoices in EUR, sent on the 1st.', wait: 10 })
era brain add "Ada Lovelace prefers invoices in EUR, sent on the 1st." --wait

Araç add_memory — girdi:

{
  "text": {
    "type": "string",
    "description": "What to remember (or use facts)"
  },
  "facts": {
    "type": "array",
    "description": "Ready-made facts: [{ statement, kind?, about?: [{ name, type }] }]",
    "items": {
      "type": "object"
    }
  },
  "visibility": {
    "type": "string",
    "enum": [
      "workspace",
      "private"
    ],
    "description": "Default workspace"
  },
  "source_label": {
    "type": "string",
    "description": "Where it came from, e.g. \"Claude Code session\""
  }
}

Yanıt

202 döner

{
  "job": {
    "id": "6b1d…",
    "status": "done"
  },
  "memories": [
    {
      "id": "0f3a…",
      "content": "Ada Lovelace prefers invoices in EUR.",
      "kind": "preference",
      "visibility": "workspace",
      "entities": [
        {
          "id": "91c2…",
          "name": "Ada Lovelace",
          "type": "person"
        }
      ],
      "created_at": "2026-10-22T09:12:03Z"
    }
  ]
}

Hatalar: 401 unauthorized · 404 not_found (Brain is outside this credential) · 403 forbidden (read-only credential) · 409 no_brain · learning_off · 422 invalid_input

İşleme durumu

Eklediğin bir hafızanın nerede olduğu: kuyrukta, işleniyor, bitti ya da başarısız — bittiğinde de saklanan ve senin görebildiğin hafızalar.

GEThttps://app.getera.io/api/v1/brain/jobs/{id}
API anahtarı ya da OAuth belirteci · brain:read

Örnek

curl "https://app.getera.io/api/v1/brain/jobs/JOB_ID" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.job('6b1d…')
era brain job 6b1d…

Yanıt

200 döner

{
  "job": {
    "id": "6b1d…",
    "status": "done",
    "error": null
  },
  "memories": []
}

Hatalar: 401 unauthorized · 404 not_found

Karma hatırlama: anahtar kelime (Türkçe ve İngilizce PostgreSQL tam metin) ve anlamsal (yerel e5 gömmeleri) kolları yan yana çalışır ve sıralamaya göre birleştirilir; aynı şey hakkında daha yeni bir bilgi eskisinin üstüne konur. graph: true ile sorunun adını verdiği varlıklar arasındaki tipli ilişki yolları da döner. Yalnızca çağıranın görebildiği aranır.

POSThttps://app.getera.io/api/v1/brain/search
API anahtarı ya da OAuth belirteci · brain:read

Tarayıcıdan ya da hızlı bir deneme için: GET /api/v1/brain/search?q=…&limit=…&graph=true.

Gövde

AlanTürZorunluNotlar
querystringevetSoru, herhangi bir dilde. · min 1 · max 500
limitintegerSonuç, 1–30. · default 10 · ≥ 1 · ≤ 30
graphbooleanİlişki yollarını da döndür. · default false

Örnek

curl -X POST "https://app.getera.io/api/v1/brain/search" \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"How does Ada want to be invoiced?","limit":5}'
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

const { results } = await brain.search('How does Ada want to be invoiced?')
era brain search "How does Ada want to be invoiced?"

Araç search_memory — girdi:

{
  "query": {
    "type": "string",
    "description": "The question, in any language"
  },
  "limit": {
    "type": "number",
    "description": "1-30, default 10"
  },
  "graph": {
    "type": "boolean",
    "description": "Also return typed relationship paths"
  }
}

Yanıt

200 döner

{
  "query": "How does Ada want to be invoiced?",
  "used_vector": true,
  "results": [
    {
      "id": "0f3a…",
      "content": "Ada Lovelace prefers invoices in EUR.",
      "kind": "preference",
      "score": 0.0331,
      "created_at": "2026-10-22T09:12:03Z"
    }
  ]
}

Hatalar: 401 unauthorized · 404 not_found (Brain is outside this credential) · 422 invalid_input

Hafızaları listele

Beyin’in şu an bildikleri, en yeni önce; kaynakları ve her bilginin adını verdiği varlıklarla. Kelimeye, türe, varlığa ya da kaynak türüne göre süz.

GEThttps://app.getera.io/api/v1/brain/memories
API anahtarı ya da OAuth belirteci · brain:read

Sorgu parametreleri

AlanTürZorunluNotlar
qstringAranacak kelimeler.
kindfact · preference · decision · commitment · episodeBilgi türü.
entity_idstring (uuid)Yalnızca bu varlığı anan bilgiler.
sourcenote · conversation · record · file · web · meeting · call · chat · document · connector · workflow_run · researchYalnızca bu tür kaynaktan gelen bilgiler.
limitinteger1–100. · default 25 · ≥ 1 · ≤ 100
cursorstringÖnceki sayfanın next_cursor değeri.

Örnek

curl "https://app.getera.io/api/v1/brain/memories?q=invoice&limit=10" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

const { data } = await brain.list({ q: 'invoice' })
era brain list --q invoice

Yanıt

200 döner

{
  "data": [
    {
      "id": "0f3a…",
      "content": "Ada Lovelace prefers invoices in EUR.",
      "kind": "preference",
      "visibility": "workspace",
      "source": {
        "kind": "note",
        "label": "Call notes"
      },
      "entities": [],
      "created_at": "2026-10-22T09:12:03Z"
    }
  ],
  "next_cursor": null
}

Hatalar: 401 unauthorized · 404 not_found · 422 invalid_input

Bir hafızayı getir

Tek bir bilgi: kaynağı, adını verdiği varlıklar ve geçmişi (yerine geçtiği bilgiler).

GEThttps://app.getera.io/api/v1/brain/memories/{id}
API anahtarı ya da OAuth belirteci · brain:read

Örnek

curl "https://app.getera.io/api/v1/brain/memories/MEMORY_ID" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.get('0f3a…')
era brain get 0f3a…

Yanıt

200 döner

{
  "data": {
    "id": "0f3a…",
    "content": "Ada Lovelace prefers invoices in EUR.",
    "kind": "preference",
    "visibility": "workspace",
    "history": []
  }
}

Hatalar: 401 unauthorized · 404 not_found (absent and not-yours answer the same)

Bir hafızayı düzelt

İfadeyi düzelt (eski sürüm geçmişte kalır, artık hatırlanmaz), doğrula, kategorisini değiştir ya da yalnızca sende kalsın. Beyin ekranının kendi aksiyonlarını çalıştırır (ai.review_brain_fact, ai.refile_brain_fact).

PATCHhttps://app.getera.io/api/v1/brain/memories/{id}
API anahtarı ya da OAuth belirteci · brain:write

Gövde

AlanTürZorunluNotlar
contentstringDoğru ifade. · min 3 · max 4000
confirmbooleanBir kişi tarafından doğrulandı olarak işaretle.
visibilityprivateBundan sonra yalnızca sende kalsın.
categorypreference · rule · procedure · factKategori.

Örnek

curl -X PATCH "https://app.getera.io/api/v1/brain/memories/MEMORY_ID" \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Ada Lovelace prefers invoices in GBP since October."}'
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.update('0f3a…', { content: 'Ada prefers invoices in GBP since October.' })
era brain correct 0f3a… "Ada prefers invoices in GBP since October."

Yanıt

200 döner

{
  "ok": true,
  "id": "0f3a…"
}

Hatalar: 401 unauthorized · 403 forbidden · 404 not_found · 409 fact_not_found · not_current · unchanged · 422 invalid_input

Bir hafızayı unut

Era onu hemen kullanmayı bırakır (artık kimse hatırlamaz). Denetim kaydı unutulduğunu ve kimin unuttuğunu tutar. Bir kişisel veri talebi için kalıcı silme, yöneticiler için Beyin ekranında kalır.

DELhttps://app.getera.io/api/v1/brain/memories/{id}
API anahtarı ya da OAuth belirteci · brain:write

Örnek

curl -X DELETE "https://app.getera.io/api/v1/brain/memories/MEMORY_ID" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.forget('0f3a…')
era brain forget 0f3a…

Araç forget_memory — girdi:

{
  "memory_id": {
    "type": "string",
    "description": "Memory id"
  },
  "about": {
    "type": "string",
    "description": "Or: what to forget, in words"
  }
}

Yanıt

200 döner

{
  "ok": true
}

Hatalar: 401 unauthorized · 403 forbidden · 404 not_found · 409 nothing_to_forget

Varlıkları listele

Beyin’in bildiği kişiler, şirketler, ürünler ve konular; her birinin adını veren görünür bilgi sayısıyla.

GEThttps://app.getera.io/api/v1/brain/entities
API anahtarı ya da OAuth belirteci · brain:read

Sorgu parametreleri

AlanTürZorunluNotlar
qstringAd ya da takma ad içerir.
typestringperson, customer, company, product, project, topic …
limitinteger1–100. · default 25 · ≥ 1 · ≤ 100

Örnek

curl "https://app.getera.io/api/v1/brain/entities?q=Ada" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.entities({ q: 'Ada' })
era brain entities --q Ada

Yanıt

200 döner

{
  "data": [
    {
      "id": "91c2…",
      "name": "Ada Lovelace",
      "type": "person",
      "aliases": [
        "Ada"
      ],
      "facts": 4
    }
  ]
}

Hatalar: 401 unauthorized · 404 not_found

Bir varlık ve komşuları

Tek bir varlık, diğer varlıklarla tipli ilişkileri (works_at, supplies, owns …) ve onu anan en yeni bilgiler.

GEThttps://app.getera.io/api/v1/brain/entities/{id}
API anahtarı ya da OAuth belirteci · brain:read

Örnek

curl "https://app.getera.io/api/v1/brain/entities/ENTITY_ID" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.entity('91c2…')
era brain entity 91c2…

Yanıt

200 döner

{
  "data": {
    "id": "91c2…",
    "name": "Ada Lovelace",
    "type": "person",
    "relations": [
      {
        "direction": "out",
        "relation": "works_at",
        "entity": {
          "id": "7aa0…",
          "name": "Analytical Engines Ltd",
          "type": "company"
        }
      }
    ],
    "facts": []
  }
}

Hatalar: 401 unauthorized · 404 not_found

Bir soru için çizge yolları

Era’nın kendi sohbetinin kullandığı okuma yolu: sorunun adını verdiği varlıklara tutunur, tipli ilişkiler üzerinde üç adıma kadar yürür (çok bağlantılı düğümlerden geçmeden), en iyi yolları döner — her adım onu söyleyen hafızayla — ve bir LLM için kısa, kaynaklı bir bağlam.

GEThttps://app.getera.io/api/v1/brain/graph
API anahtarı ya da OAuth belirteci · brain:read

Sorgu parametreleri

AlanTürZorunluNotlar
qstringSoru. · min 1 · max 500
limitintegerYol, 1–12. · default 6 · ≥ 1 · ≤ 12

Örnek

curl "https://app.getera.io/api/v1/brain/graph?q=Who%20supplies%20the%20company%20Ada%20works%20at%3F" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.graph('Who supplies the company Ada works at?')
era brain graph "Who supplies the company Ada works at?"

Araç graph_paths — girdi:

{
  "query": {
    "type": "string",
    "description": "A question naming the entities"
  },
  "from": {
    "type": "string",
    "description": "An entity name (with to)"
  },
  "to": {
    "type": "string",
    "description": "Another entity name"
  }
}

Yanıt

200 döner

{
  "query": "Who supplies the company Ada works at?",
  "anchors": [
    {
      "id": "91c2…",
      "name": "Ada Lovelace",
      "type": "person"
    }
  ],
  "paths": [
    {
      "score": 2.4,
      "hops": [
        {
          "from": "Ada Lovelace",
          "relation": "works_at",
          "to": "Analytical Engines Ltd"
        },
        {
          "from": "Babbage Parts",
          "relation": "supplies",
          "to": "Analytical Engines Ltd"
        }
      ]
    }
  ],
  "context": "…"
}

Hatalar: 401 unauthorized · 404 not_found · 422 invalid_input

İki varlık arasındaki yol

Adı verilen iki varlık arasındaki en kısa tipli ilişki zinciri (belirlenimci; hiçbir model çağrılmaz).

GEThttps://app.getera.io/api/v1/brain/paths
API anahtarı ya da OAuth belirteci · brain:read

Sorgu parametreleri

AlanTürZorunluNotlar
fromstringBir varlık adı.
tostringBaşka bir varlık adı.
max_depthintegerAdım, 1–6. · default 4 · ≥ 1 · ≤ 6

Örnek

curl "https://app.getera.io/api/v1/brain/paths?from=Ada%20Lovelace&to=Babbage%20Parts" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.paths('Ada Lovelace', 'Babbage Parts')
era brain path "Ada Lovelace" "Babbage Parts"

Yanıt

200 döner

{
  "found": true,
  "from": {
    "id": "91c2…",
    "name": "Ada Lovelace",
    "type": "person"
  },
  "to": {
    "id": "3c1e…",
    "name": "Babbage Parts",
    "type": "company"
  },
  "hops": [
    {
      "from": "Ada Lovelace",
      "relation": "works_at",
      "to": "Analytical Engines Ltd"
    },
    {
      "from": "Babbage Parts",
      "relation": "supplies",
      "to": "Analytical Engines Ltd"
    }
  ]
}

Hatalar: 401 unauthorized · 404 not_found · 422 invalid_input

Kaynaklar

Beyin’in bildiklerinin nereden geldiği: bu çalışma alanının bağlı kaynakları (Google Drive, Notion …) ve kaynak türüne göre kaç görünür bilgi verdiği, en son ne zaman.

GEThttps://app.getera.io/api/v1/brain/sources
API anahtarı ya da OAuth belirteci · brain:read

Örnek

curl "https://app.getera.io/api/v1/brain/sources" \
  -H "Authorization: Bearer $ERA_API_KEY"
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.sources()
era brain sources

Yanıt

200 döner

{
  "connected": [],
  "kinds": [
    {
      "kind": "note",
      "memories": 12,
      "last_at": "2026-10-22T09:12:03Z"
    }
  ]
}

Hatalar: 401 unauthorized · 404 not_found

Bir sonucu açıkla

Bir bilginin bir soruya neden döndüğü (ya da dönmediği): anahtar kelime ve anlamsal kollardaki sırası, birleşik puan, yenilik ve önem, soruyla ortak adı geçen varlıklar ve onu sana gösteren görünürlük kuralı.

POSThttps://app.getera.io/api/v1/brain/explain
API anahtarı ya da OAuth belirteci · brain:read

Gövde

AlanTürZorunluNotlar
querystringevetSoru. · min 1 · max 500
memory_idstring (uuid)evetAçıklanacak bilgi.

Örnek

curl -X POST "https://app.getera.io/api/v1/brain/explain" \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"How does Ada want to be invoiced?","memory_id":"0f3a…"}'
import { createBrain } from '@getera/brain' // or: createEra(...).brain
const brain = createBrain({ apiKey: process.env.ERA_API_KEY })

await brain.explain('How does Ada want to be invoiced?', '0f3a…')
era brain explain "How does Ada want to be invoiced?" 0f3a…

Yanıt

200 döner

{
  "returned": true,
  "rank": 1,
  "score": 0.0331,
  "keyword": {
    "matched": true,
    "terms": [
      "ada",
      "invoic"
    ]
  },
  "semantic": {
    "similarity": 0.87
  },
  "shared_entities": [
    {
      "id": "91c2…",
      "name": "Ada Lovelace",
      "type": "person"
    }
  ],
  "recency_days": 0.2,
  "importance": 0.6,
  "superseded": false,
  "visible_because": "Shared with the workspace; you can read Brain."
}

Hatalar: 401 unauthorized · 404 not_found · 422 invalid_input

MCP araçları

Era’nın MCP sunucusunda https://app.getera.io/api/mcp?tools=brain yalnızca bunları listeler (?tools=brain olmadan işletme araçlarının yanında dururlar).

AraçGerekirNe yapar
search_memorybrain:readİnsanlar, müşteriler, tercihler, kararlar ya da geçmiş işler hakkında cevap vermeden önce Era Beyin’de ara. Karma anahtar kelime + anlamsal hatırlama; iki bilgi çeliştiğinde en yenisi önce. Yalnızca giriş yapan kişinin görebildikleri.
add_memorybrain:writeBu oturumdan sonra da hatırlanmaya değer olanı kaydet: kalıcı bir tercih, bir karar ve nedeni, bir taahhüt, bir kişi, müşteri ya da proje hakkında bir bilgi. Her bilgi tek, kendi başına anlamlı bir cümle. Sır, parola ya da gelip geçici sohbet kaydedilmez. visibility "private" yalnızca giriş yapan kişide tutar.
graph_pathsbrain:readŞeylerin nasıl bağlı olduğu: bir sorunun adını verdiği varlıklar arasındaki tipli ilişki yolları (works_at, supplies, owns …), her adım onu söyleyen hafızayla. İki adlı varlık arasındaki en kısa yol için "from" ve "to" ver.
forget_memorybrain:writeEra’nın bir hafızayı kullanmasını durdur: kimliğiyle (search_memory’den) ya da sözle tarif ederek ("about"). Kişi bir şeyin yanlış ya da artık geçerli olmadığını söylediğinde kullan; değiştiyse yeni bilgiyle add_memory tercih et.
Bu sayfa yardımcı oldu mu?