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
| Scope | Ne yapar |
|---|---|
brain | Hafızaları okur ve yazar (kişinin Beyin’de yapabildiği her şey). |
brain:read | Arama, çizge, liste, getirme, açıklama, kaynaklar, işleme durumu. |
brain:write | Ayrıca ekleme, düzeltme ve unutma. brain:read içerir. |
*, ai, ai:read, ai:write | Beyin’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
| Adres | Gerekir | Ne yapar | |
|---|---|---|---|
POST | /api/v1/brain/memories | brain:write | Hafıza ekle |
GET | /api/v1/brain/jobs/{id} | brain:read | İşleme durumu |
POST | /api/v1/brain/search | brain:read | Hafızada ara |
GET | /api/v1/brain/memories | brain:read | Hafızaları listele |
GET | /api/v1/brain/memories/{id} | brain:read | Bir hafızayı getir |
PATCH | /api/v1/brain/memories/{id} | brain:write | Bir hafızayı düzelt |
DELETE | /api/v1/brain/memories/{id} | brain:write | Bir hafızayı unut |
GET | /api/v1/brain/entities | brain:read | Varlıkları listele |
GET | /api/v1/brain/entities/{id} | brain:read | Bir varlık ve komşuları |
GET | /api/v1/brain/graph | brain:read | Bir soru için çizge yolları |
GET | /api/v1/brain/paths | brain:read | İki varlık arasındaki yol |
GET | /api/v1/brain/sources | brain:read | Kaynaklar |
POST | /api/v1/brain/explain | brain:read | Bir 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.
https://app.getera.io/api/v1/brain/memoriesGövde
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
text | string | Serbest metin: bir not, bir e-posta, bir döküm. 20–24 000 karakter. · min 20 · max 24000 | |
messages | array of object | Bir konuşma; her mesaj konuşanıyla saklanır. · ≤ 200 items | |
facts | array of object | Hazır bilgiler: verildiği gibi saklanır (çıkarım yok). · ≤ 40 items | |
record | object | Yapılandırılmış bir kayıt (kendi sisteminden bir talep, kişi ya da sipariş). | |
source | object | Nereden geldiği. Hatırlanan her bilgiyle gösterilir. Varsayılan: çağıranın notu. | |
visibility | workspace · private | private: yalnızca sen hatırlarsın. · default "workspace" | |
module | string | Yalnızca okuyabildiğin bir modülün okuyucularına açık tut (ör. crm). · max 64 | |
wait | integer | Hafı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." --waitAraç 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.
https://app.getera.io/api/v1/brain/jobs/{id}Ö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
Hafızada ara
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.
https://app.getera.io/api/v1/brain/searchTarayıcıdan ya da hızlı bir deneme için: GET /api/v1/brain/search?q=…&limit=…&graph=true.
Gövde
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
query | string | evet | Soru, herhangi bir dilde. · min 1 · max 500 |
limit | integer | Sonuç, 1–30. · default 10 · ≥ 1 · ≤ 30 | |
graph | boolean | İ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.
https://app.getera.io/api/v1/brain/memoriesSorgu parametreleri
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
q | string | Aranacak kelimeler. | |
kind | fact · preference · decision · commitment · episode | Bilgi türü. | |
entity_id | string (uuid) | Yalnızca bu varlığı anan bilgiler. | |
source | note · conversation · record · file · web · meeting · call · chat · document · connector · workflow_run · research | Yalnızca bu tür kaynaktan gelen bilgiler. | |
limit | integer | 1–100. · default 25 · ≥ 1 · ≤ 100 | |
cursor | string | Ö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 invoiceYanı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).
https://app.getera.io/api/v1/brain/memories/{id}Ö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).
https://app.getera.io/api/v1/brain/memories/{id}Gövde
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
content | string | Doğru ifade. · min 3 · max 4000 | |
confirm | boolean | Bir kişi tarafından doğrulandı olarak işaretle. | |
visibility | private | Bundan sonra yalnızca sende kalsın. | |
category | preference · rule · procedure · fact | Kategori. |
Ö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.
https://app.getera.io/api/v1/brain/memories/{id}Ö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.
https://app.getera.io/api/v1/brain/entitiesSorgu parametreleri
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
q | string | Ad ya da takma ad içerir. | |
type | string | person, customer, company, product, project, topic … | |
limit | integer | 1–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 AdaYanı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.
https://app.getera.io/api/v1/brain/entities/{id}Ö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.
https://app.getera.io/api/v1/brain/graphSorgu parametreleri
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
q | string | Soru. · min 1 · max 500 | |
limit | integer | Yol, 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).
https://app.getera.io/api/v1/brain/pathsSorgu parametreleri
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
from | string | Bir varlık adı. | |
to | string | Başka bir varlık adı. | |
max_depth | integer | Adı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.
https://app.getera.io/api/v1/brain/sourcesÖ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 sourcesYanı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ı.
https://app.getera.io/api/v1/brain/explainGövde
| Alan | Tür | Zorunlu | Notlar |
|---|---|---|---|
query | string | evet | Soru. · min 1 · max 500 |
memory_id | string (uuid) | evet | Açı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ç | Gerekir | Ne yapar |
|---|---|---|
search_memory | brain: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_memory | brain:write | Bu 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_paths | brain: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_memory | brain:write | Era’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. |