Uygulamalar API — Era Belgeleri

Uygulamalar modülünün tüm işlemleri (14) ve veri modelleri (1): adresler, izinler, girdiler, ön koşullar, olaylar ve örnekler.

Bağladığınız uygulama ve servisler ile onlara gönderilen güncellemeler.

Modül kodu apps · 14 işlem · 1 veri modeli · 12 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ı: apps (hepsi), apps:read (yalnız okuma) ya da apps:<yetenek>.

Kaynaklar

Kaynak	Tablo	Listeleme ve okuma	POST	PATCH	DELETE
`app_connection_choices`	`app_connection_choice`	`/api/v1/app_connection_choices`

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
`apps.add_connection`	`apps:read`	Hesap ekle
`apps.connect`	`apps:manage`	Bağlantıyı kaydet
`apps.connect_whatsapp`	`apps:read`	WhatsApp Business bağla
`apps.disconnect`	`apps:delete`	Bağlantıyı kes
`apps.record_failure`	`apps:handle`	Bağlantı hatasını kaydet
`apps.record_healthy`	`apps:handle`	Başarılı bağlantı testini kaydet
`apps.record_poll`	`apps:handle`	Bağlı uygulamanın yoklamasını kaydet
`apps.register_installation`	`apps:manage`	Kurulumu kaydet
`apps.rotate_secret`	`apps:handle`	Bağlantının anahtarını yenile
`apps.set_connection_choice`	`apps:read`	Hangi hesabın kullanılacağını seç
`apps.set_connection_owner`	`apps:read`	Bağlantının kimin olduğunu değiştir
`apps.set_paused`	`apps:manage`	Bağlantıyı duraklat veya sürdür
`apps.store_secret`	`apps:manage`	Sır sakla
`apps.update_connection`	`apps:manage`	Bağlantıyı değiştir

`apps.add_connection`

Hesap ekle — Bir uygulamaya bir hesap daha bağlar — senin ya da şirketin. Anahtar şifrelenip saklanır.

Gereken izin apps:read · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır) · Era çalıştırırken bir kişiye onaylatır

POSThttps://app.getera.io/api/v1/actions/apps.add_connection

API anahtarı ya da OAuth token · apps:read

Girdi

Alan	Tür	Zorunlu	Açıklama
`provider`	string	evet	Uygulama · en çok 64
`label`	string	evet	Ad · en çok 160
`kind`	string (enum)	evet	Tür · İzin verilen değerler: `oauth2`, `api_key`, `basic`
`value`	string		Anahtar · en çok 16000
`secretRef`	string		Gizli anahtarın saklandığı yer · en çok 200
`accountRef`	string		Hesap (örneğin info@…) · en çok 200
`owner`	string (enum)		Kimin · İzin verilen değerler: `me`, `workspace`
`share`	string (enum)		Kimler kullanabilir · İzin verilen değerler: `me`, `team`, `workspace`
`teamId`	uuid		Ekip

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`empty_label`	Bağlantının bir adı olmalı.
`bad_provider`	Uygulama adı küçük harfli bir kısa ad olmalı.
`not_manager`	Şirket bağlantısını yalnızca sahip ya da yönetici ekleyebilir.
`team_required`	Bir ekiple paylaşmak için ekibi seçmeniz gerekir.
`no_secret`	Bağlantı için bir anahtar ya da giriş yapılmış bir hesap gerekir.
`label_taken`	Aynı uygulamanın iki etkin bağlantısı aynı adı taşıyamaz.

Yayımladığı olaylar: apps.connected

Neye yazar: secret (insert) — Seals the key, when one is given; credential (insert) — Writes the connection with its owner and share

curl -X POST https://app.getera.io/api/v1/actions/apps.add_connection \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"App","label":"Name","kind":"oauth2"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.add_connection", {
  provider: "App",
  label: "Name",
  kind: "oauth2"
})

era apps add_connection \
  --provider "App" \
  --label "Name" \
  --kind "oauth2"

tools/call

{
  "name": "era__apps__add_connection",
  "arguments": {
    "provider": "App",
    "label": "Name",
    "kind": "oauth2"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:read izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 empty_label, bad_provider, not_manager, team_required, no_secret, label_taken · 429 çok sık istek

`apps.connect`

Bağlantıyı kaydet — Bu çalışma alanının bir şeye bağlı olduğunu söyleyen tek satırı yazar.

Gereken izin apps:manage · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır) · Era çalıştırırken bir kişiye onaylatır

POSThttps://app.getera.io/api/v1/actions/apps.connect

API anahtarı ya da OAuth token · apps:manage

Girdi

Alan	Tür	Zorunlu	Açıklama
`provider`	string	evet	Sağlayıcı · en çok 64
`label`	string	evet	Ad · en çok 160
`kind`	string (enum)	evet	Tür · İzin verilen değerler: `oauth2`, `api_key`, `basic`, `mcp`, `signing`
`secretRef`	string	evet	Gizli anahtarın saklandığı yer · Saklanan gizli anahtarın adı — asla anahtarın kendisi değil. Buraya hiçbir zaman erişim anahtarı yazılmaz. · en çok 200
`accountRef`	string		Sağlayıcıdaki hesap · en çok 200
`scopes`	object / array		Verilen izinler
`expiresAt`	date-time		Sona erme

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`empty_label`	Bağlantının bir adı olmalı.
`bad_provider`	Sağlayıcı küçük harfli bir kısa addır.
`bad_scopes`	Kapsamlar bir metin listesidir.
`label_taken`	Aynı sağlayıcıya ait iki etkin bağlantı aynı adı taşıyamaz.

Yayımladığı olaylar: apps.connected

Neye yazar: credential (insert) — Writes the connection. Never the secret

curl -X POST https://app.getera.io/api/v1/actions/apps.connect \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"provider":"Provider","label":"Name","kind":"oauth2","secretRef":"Where the secret is kept"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.connect", {
  provider: "Provider",
  label: "Name",
  kind: "oauth2",
  secretRef: "Where the secret is kept"
})

era apps connect \
  --provider "Provider" \
  --label "Name" \
  --kind "oauth2" \
  --secret-ref "Where the secret is kept"

tools/call

{
  "name": "era__apps__connect",
  "arguments": {
    "provider": "Provider",
    "label": "Name",
    "kind": "oauth2",
    "secretRef": "Where the secret is kept"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 empty_label, bad_provider, bad_scopes, label_taken · 429 çok sık istek

`apps.connect_whatsapp`

WhatsApp Business bağla — Bir WhatsApp Business numarasını (Meta kaydından) senin ya da şirketin bağlantısı olarak kaydeder; erişim anahtarı kasada şifreli saklanır.

Gereken izin apps:read · dışarıya ulaşır (gönderir, yayımlar ya da ücret alır)

POSThttps://app.getera.io/api/v1/actions/apps.connect_whatsapp

API anahtarı ya da OAuth token · apps:read

Girdi

Alan	Tür	Zorunlu	Açıklama
`phoneNumberId`	string	evet	Telefon numarası kimliği · en çok 40
`wabaId`	string	evet	WhatsApp Business hesap kimliği · en çok 40
`businessId`	string		İşletme portföyü kimliği · en çok 40
`displayNumber`	string	evet	Sayı · en çok 40
`verifiedName`	string		Görünen ad · en çok 200
`token`	string	evet	İşletme erişim anahtarı · en çok 4000
`pin`	string		İki adımlı PIN · en çok 6
`via`	string (enum)		Bağlayan · İzin verilen değerler: `embedded_signup`, `manual`
`owner`	string (enum)		Kimin · İzin verilen değerler: `me`, `workspace`
`share`	string (enum)		Kimler kullanabilir · İzin verilen değerler: `me`, `team`, `workspace`
`teamId`	uuid		Ekip

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`bad_whatsapp_ids`	Kimlikler Meta’nın sayısal kimlikleri, numara ise ülke koduyla birlikte tam numara olmalı.
`not_manager`	Şirketin WhatsApp hesabını yalnızca sahip ya da yönetici ekleyebilir.
`team_required`	Bir ekiple paylaşmak için ekibi seçmeniz gerekir.
`whatsapp_number_taken`	Bu numara bir iş arkadaşınızın kişisel bağlantısı (ya da yönetici değilseniz şirketin bağlantısı) olduğu için devralınamaz.

Yayımladığı olaylar: apps.connected, apps.connection_updated

Neye yazar: secret (upsert) — Seals the business token (and the PIN), rotating in place on a reconnect; credential (upsert) — One connection per number, with its owner and Meta ids

curl -X POST https://app.getera.io/api/v1/actions/apps.connect_whatsapp \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"phoneNumberId":"Phone number id","wabaId":"WhatsApp Business Account id","displayNumber":"Number","token":"Business token"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connected",
    "apps.connection_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.connect_whatsapp", {
  phoneNumberId: "Phone number id",
  wabaId: "WhatsApp Business Account id",
  displayNumber: "Number",
  token: "Business token"
})

era apps connect_whatsapp \
  --phone-number-id "Phone number id" \
  --waba-id "WhatsApp Business Account id" \
  --display-number "Number" \
  --token "Business token"

tools/call

{
  "name": "era__apps__connect_whatsapp",
  "arguments": {
    "phoneNumberId": "Phone number id",
    "wabaId": "WhatsApp Business Account id",
    "displayNumber": "Number",
    "token": "Business token"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:read izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 bad_whatsapp_ids, not_manager, team_required, whatsapp_number_taken · 429 çok sık istek

`apps.disconnect`

Bağlantıyı kes — Bağlantıyı gizler ve iptal edildi işaretler. Onunla imzalanan her şey başarısız olmaya başlar.

Gereken izin apps:delete · siler ya da geri alınamaz · Era çalıştırırken bir kişiye onaylatır

POSThttps://app.getera.io/api/v1/actions/apps.disconnect

API anahtarı ya da OAuth token · apps:delete

Girdi

Alan	Tür	Zorunlu	Açıklama
`id`	uuid	evet	Bağlantı · kimliği: `credential`

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.

Yayımladığı olaylar: apps.disconnected

Neye yazar: credential (update) — Writes the tombstone, through sql/057’s door

curl -X POST https://app.getera.io/api/v1/actions/apps.disconnect \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CREDENTIAL_ID"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.disconnected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.disconnect", {
  id: "CREDENTIAL_ID"
})

era apps disconnect \
  --id "CREDENTIAL_ID"

tools/call

{
  "name": "era__apps__disconnect",
  "arguments": {
    "id": "CREDENTIAL_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:delete izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 not_found · 429 çok sık istek

`apps.record_failure`

Bağlantı hatasını kaydet — Sağlayıcının kendi hata mesajını bağlantıda aynen saklar.

Gereken izin apps:handle · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.record_failure

API anahtarı ya da OAuth token · apps:handle

Girdi

Alan	Tür	Zorunlu	Açıklama
`id`	uuid	evet	Bağlantı · kimliği: `credential`
`message`	string	evet	Sağlayıcının yanıtı · en çok 2000

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.

Yayımladığı olaylar: apps.connection_failed

Neye yazar: credential (update) — Marks it in error and keeps the message

curl -X POST https://app.getera.io/api/v1/actions/apps.record_failure \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CREDENTIAL_ID","message":"What the provider said"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_failed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.record_failure", {
  id: "CREDENTIAL_ID",
  message: "What the provider said"
})

era apps record_failure \
  --id "CREDENTIAL_ID" \
  --message "What the provider said"

tools/call

{
  "name": "era__apps__record_failure",
  "arguments": {
    "id": "CREDENTIAL_ID",
    "message": "What the provider said"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:handle izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 not_found · 429 çok sık istek

`apps.record_healthy`

Başarılı bağlantı testini kaydet — Testi geçen bağlantının hatasını temizler ve zamanını işler.

Gereken izin apps:handle · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.record_healthy

API anahtarı ya da OAuth token · apps:handle

Girdi

Alan	Tür	Zorunlu	Açıklama
`id`	uuid	evet	Bağlantı · kimliği: `credential`

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.

Yayımladığı olaylar: apps.connection_healthy

Neye yazar: credential (update) — Back to active, error cleared, test time stamped

curl -X POST https://app.getera.io/api/v1/actions/apps.record_healthy \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CREDENTIAL_ID"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_healthy"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.record_healthy", {
  id: "CREDENTIAL_ID"
})

era apps record_healthy \
  --id "CREDENTIAL_ID"

tools/call

{
  "name": "era__apps__record_healthy",
  "arguments": {
    "id": "CREDENTIAL_ID"
  }
}

`apps.record_poll`

Bağlı uygulamanın yoklamasını kaydet — Bir kurulumun bir akışının kontrol noktasını ilerletir ve her yeni öğeyi bir kez kabul eder.

Gereken izin apps:handle · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.record_poll

API anahtarı ya da OAuth token · apps:handle

Girdi

Alan	Tür	Zorunlu	Açıklama
`credentialId`	uuid	evet	Bağlantı · kimliği: `credential`
`feed`	string	evet	Akış · en çok 64
`cursor`	string		Kontrol noktası · en çok 2000
`items`	object / array		Yeni öğeler
`error`	string		Sağlayıcının yanıtı · en çok 2000

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.
`invalid_feed`	Akış adı küçük harf, rakam ve alt çizgiden oluşur.

Yayımladığı olaylar: apps.app_event, apps.poll_failed, apps.connection_failed

Neye yazar: app_poll_state (upsert) — Moves the checkpoint, or counts the failure; app_poll_seen (insert) — Admits each item id once per feed; credential (update) — Stamps last use; goes red after three failures in a row

curl -X POST https://app.getera.io/api/v1/actions/apps.record_poll \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"credentialId":"CREDENTIAL_ID","feed":"Feed"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.app_event",
    "apps.poll_failed",
    "apps.connection_failed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.record_poll", {
  credentialId: "CREDENTIAL_ID",
  feed: "Feed"
})

era apps record_poll \
  --credential-id "CREDENTIAL_ID" \
  --feed "Feed"

tools/call

{
  "name": "era__apps__record_poll",
  "arguments": {
    "credentialId": "CREDENTIAL_ID",
    "feed": "Feed"
  }
}

`apps.register_installation`

Kurulumu kaydet — Bağlanan bir konektörü, OAuth hesabını veya MCP sunucusunu bu çalışma alanının kurulum kaydı yapar; test, duraklatma ve kaldırma tek yerden yapılır.

Gereken izin apps:manage · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.register_installation

API anahtarı ya da OAuth token · apps:manage

Girdi

Alan	Tür	Zorunlu	Açıklama
`source`	string (enum)	evet	Bağlandığı yer · İzin verilen değerler: `connector`, `oauth`, `mcp_server`, `engine_credential`
`sourceRef`	string	evet	Motor kaydı · en çok 200
`provider`	string	evet	Sağlayıcı · en çok 64
`label`	string	evet	Ad · en çok 160
`kind`	string (enum)	evet	Tür · İzin verilen değerler: `oauth2`, `api_key`, `basic`, `mcp`, `signing`
`accountRef`	string		Sağlayıcıdaki hesap · en çok 200
`scopes`	object / array		Verilen izinler

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`empty_label`	Bağlantının bir adı olmalı.
`bad_provider`	Sağlayıcı küçük harfli bir kısa addır.
`bad_scopes`	Kapsamlar bir metin listesidir.

Yayımladığı olaylar: apps.connected

Neye yazar: credential (insert) — Writes the installation row, or returns the existing one

curl -X POST https://app.getera.io/api/v1/actions/apps.register_installation \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"source":"connector","sourceRef":"Engine row","provider":"Provider","label":"Name","kind":"oauth2"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connected"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.register_installation", {
  source: "connector",
  sourceRef: "Engine row",
  provider: "Provider",
  label: "Name",
  kind: "oauth2"
})

era apps register_installation \
  --source "connector" \
  --source-ref "Engine row" \
  --provider "Provider" \
  --label "Name" \
  --kind "oauth2"

tools/call

{
  "name": "era__apps__register_installation",
  "arguments": {
    "source": "connector",
    "sourceRef": "Engine row",
    "provider": "Provider",
    "label": "Name",
    "kind": "oauth2"
  }
}

`apps.rotate_secret`

Bağlantının anahtarını yenile — Yenilenen OAuth anahtarını aynı kasa kaydının üzerine şifreler.

Gereken izin apps:handle · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.rotate_secret

API anahtarı ya da OAuth token · apps:handle

Girdi

Alan	Tür	Zorunlu	Açıklama
`credentialId`	uuid	evet	Bağlantı · kimliği: `credential`
`value`	string	evet	Gizli anahtar · en çok 16000

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bu bağlantı bulunamadı.
`no_vault_secret`	Yalnız kasadaki bir anahtar yenilenir.

Yayımladığı olaylar: apps.connection_updated

Neye yazar: secret (update) — Rotates the sealed value in place

curl -X POST https://app.getera.io/api/v1/actions/apps.rotate_secret \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"credentialId":"CREDENTIAL_ID","value":"Secret"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.rotate_secret", {
  credentialId: "CREDENTIAL_ID",
  value: "Secret"
})

era apps rotate_secret \
  --credential-id "CREDENTIAL_ID" \
  --value "Secret"

tools/call

{
  "name": "era__apps__rotate_secret",
  "arguments": {
    "credentialId": "CREDENTIAL_ID",
    "value": "Secret"
  }
}

`apps.set_connection_choice`

Hangi hesabın kullanılacağını seç — Bir Era’nın, iş akışının ya da sohbetlerinin bir uygulamada hangi hesabı kullanacağı: kendi hesabın, şirketinki ya da adıyla biri.

Gereken izin apps:read · veriyi değiştirir

POSThttps://app.getera.io/api/v1/app_connection_choices/actions/set_connection_choice

API anahtarı ya da OAuth token · apps:read

Asıl adres: POST /api/v1/actions/apps.set_connection_choice

Girdi

Alan	Tür	Zorunlu	Açıklama
`subjectType`	string (enum)	evet	İçin · İzin verilen değerler: `chat`, `agent`, `workflow`, `voice_agent`
`subjectId`	string		Hangisi · en çok 200
`family`	string	evet	Uygulama · en çok 64
`pick`	string (enum)	evet	Kullan · İzin verilen değerler: `mine`, `workspace`, `connection`
`connectionId`	uuid		Bağlantı · kimliği: `credential`

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`subject_required`	Bir Era, iş akışı ya da sesli ajan seçilmeli.
`connection_required`	Belirli bir bağlantı seçimi için bağlantıyı seçmeniz gerekir.
`connection_not_found`	Bağlantı bu çalışma alanında bulunmalı.
`provider_mismatch`	Bağlantı aynı uygulamaya ait olmalı.
`connection_not_usable`	Yalnızca seçen kişinin kullanabildiği bir bağlantı seçilebilir.

Yayımladığı olaylar: apps.connection_choice_set

Neye yazar: app_connection_choice (upsert) — One row per thing and app

curl -X POST https://app.getera.io/api/v1/app_connection_choices/actions/set_connection_choice \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"subjectType":"chat","family":"App","pick":"mine"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_choice_set"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.appConnectionChoices.setConnectionChoice({
  subjectType: "chat",
  family: "App",
  pick: "mine"
})

era app_connection_choices set_connection_choice \
  --subject-type "chat" \
  --family "App" \
  --pick "mine"

tools/call

{
  "name": "era__apps__set_connection_choice",
  "arguments": {
    "subjectType": "chat",
    "family": "App",
    "pick": "mine"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:read izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 subject_required, connection_required, connection_not_found, provider_mismatch, connection_not_usable · 429 çok sık istek

`apps.set_connection_owner`

Bağlantının kimin olduğunu değiştir — Kişisel mi şirketin mi, ve başka kimlerin kullanabileceği. Kişisel bağlantıyı yalnız sahibi değiştirir.

Gereken izin apps:read · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.set_connection_owner

API anahtarı ya da OAuth token · apps:read

Girdi

Alan	Tür	Zorunlu	Açıklama
`id`	uuid	evet	Bağlantı · kimliği: `credential`
`owner`	string (enum)	evet	Kimin · İzin verilen değerler: `me`, `workspace`
`share`	string (enum)		Kimler kullanabilir · İzin verilen değerler: `me`, `team`, `workspace`
`teamId`	uuid		Ekip

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.
`not_owner`	Kişisel bir bağlantıyı yalnızca sahibi değiştirebilir.
`not_manager`	Şirket bağlantılarını yalnızca sahip ya da yönetici değiştirebilir.
`workspace_owned`	Şirket bağlantısı birinin kişisel bağlantısına dönüştürülemez.
`team_required`	Bir ekiple paylaşmak için ekibi seçmeniz gerekir.

Yayımladığı olaylar: apps.connection_updated

Neye yazar: credential (update) — Sets owner_user_id, share_scope and share_team_id

curl -X POST https://app.getera.io/api/v1/actions/apps.set_connection_owner \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CREDENTIAL_ID","owner":"me"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.set_connection_owner", {
  id: "CREDENTIAL_ID",
  owner: "me"
})

era apps set_connection_owner \
  --id "CREDENTIAL_ID" \
  --owner "me"

tools/call

{
  "name": "era__apps__set_connection_owner",
  "arguments": {
    "id": "CREDENTIAL_ID",
    "owner": "me"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:read izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 not_found, not_owner, not_manager, workspace_owned, team_required · 429 çok sık istek

`apps.set_paused`

Bağlantıyı duraklat veya sürdür — Duraklatılmış bağlantı sırrını ve geçmişini korur; sohbetler, ajanlar ve iş akışları onu atlar.

Gereken izin apps:manage · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.set_paused

API anahtarı ya da OAuth token · apps:manage

Girdi

Alan	Tür	Zorunlu	Açıklama
`id`	uuid	evet	Bağlantı · kimliği: `credential`
`paused`	boolean	evet	Duraklatıldı

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.
`not_pausable`	İptal edilmiş veya süresi dolmuş bir bağlantı duraklatılmaz, yeniden bağlanır.
`no_secret`	Hiçbir sırrı göstermeyen bir bağlantı sürdürülemez.

Yayımladığı olaylar: apps.paused, apps.resumed

Neye yazar: credential (update) — Flips the status between paused and active

curl -X POST https://app.getera.io/api/v1/actions/apps.set_paused \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CREDENTIAL_ID","paused":true}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.paused",
    "apps.resumed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.set_paused", {
  id: "CREDENTIAL_ID",
  paused: true
})

era apps set_paused \
  --id "CREDENTIAL_ID" \
  --paused true

tools/call

{
  "name": "era__apps__set_paused",
  "arguments": {
    "id": "CREDENTIAL_ID",
    "paused": true
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 not_found, not_pausable, no_secret · 429 çok sık istek

`apps.store_secret`

Sır sakla — Bir anahtarı, erişim anahtarını veya şifreyi kasada mühürler. Değiştirilebilir, asla geri okunamaz.

Gereken izin apps:manage · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.store_secret

API anahtarı ya da OAuth token · apps:manage

Girdi

Alan	Tür	Zorunlu	Açıklama
`credentialId`	uuid		Bağlantı · kimliği: `credential`
`value`	string	evet	Gizli anahtar · en çok 16000

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.

Yayımladığı olaylar: apps.connection_updated

Neye yazar: secret (upsert) — Seals the value; a second call rotates it in place; credential (update) — Points the connection at the vault secret

curl -X POST https://app.getera.io/api/v1/actions/apps.store_secret \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"value":"Secret"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.store_secret", {
  value: "Secret"
})

era apps store_secret \
  --value "Secret"

tools/call

{
  "name": "era__apps__store_secret",
  "arguments": {
    "value": "Secret"
  }
}

`apps.update_connection`

Bağlantıyı değiştir — Yeniden adlandırır, başka bir saklı sırra bağlar veya süresi doldu işaretler.

Gereken izin apps:manage · veriyi değiştirir

POSThttps://app.getera.io/api/v1/actions/apps.update_connection

API anahtarı ya da OAuth token · apps:manage

Girdi

Alan	Tür	Zorunlu	Açıklama
`id`	uuid	evet	Bağlantı · kimliği: `credential`
`label`	string		Ad · en çok 160
`secretRef`	string		Gizli anahtarın saklandığı yer · Saklanan gizli anahtarın adı — asla anahtarın kendisi değil. Buraya hiçbir zaman erişim anahtarı yazılmaz. · en çok 200
`accountRef`	string		Sağlayıcıdaki hesap · en çok 200
`scopes`	object / array		Verilen izinler
`expiresAt`	date-time		Sona erme
`status`	string (enum)		Durum · İzin verilen değerler: `active`, `expired`, `revoked`, `error`

Ön koşullar

Koşul tutmazsa işlem 409 ve şu kodlardan biriyle reddedilir:

Kod	Ne zaman reddedilir
`not_found`	Bağlantı bu çalışma alanında bulunmalı.
`empty_label`	Bağlantının bir adı olmalı.
`bad_scopes`	Kapsamlar bir metin listesidir.

Yayımladığı olaylar: apps.connection_updated

Neye yazar: credential (update) — Rewrites the connection

curl -X POST https://app.getera.io/api/v1/actions/apps.update_connection \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"CREDENTIAL_ID"}'

Yanıt

{
  "ok": true,
  "result": "…",
  "events": [
    "apps.connection_updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.actions.run("apps.update_connection", {
  id: "CREDENTIAL_ID"
})

era apps update_connection \
  --id "CREDENTIAL_ID"

tools/call

{
  "name": "era__apps__update_connection",
  "arguments": {
    "id": "CREDENTIAL_ID"
  }
}

Hatalar: 401 kimlik bilgisi yok ya da süresi dolmuş · 403 kimlik bilgisinde apps:manage izni yok · 404 kayıt ya da modül erişim dışında · 422 geçersiz girdi (problems[]) · 409 not_found, empty_label, bad_scopes · 429 çok sık istek

Veri modelleri

AppConnectionChoice

Tablo app_connection_choice · Kaynak app_connection_choices

GET /api/v1/app_connection_choices
GET /api/v1/app_connection_choices/{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`
`subject_type`	string · `text`		`chat`, `agent`, `workflow`, `voice_agent`
`subject_id`	string · `text`
`family`	string · `text`
`pick`	string · `text`		`mine`, `workspace`, `connection`
`connection_id`	string (uuid) · `uuid`	evet		`credential`
`created_by`	string (uuid) · `uuid`	evet		`app_user`
`created_at`	string (date-time) · `timestamptz`
`updated_at`	string (date-time) · `timestamptz`

Birincil anahtar: id

Tekil: workspace_id, subject_type, subject_id, family

Denetimler:

CHECK ((family ~ '^[a-z][a-z0-9_]{1,63}$'::text))

Olaylar

İş akışları ve webhook'lar bu olaylara tepki verir.

Olay	Ne olur	Taşıdığı alanlar
`apps.app_event`	Bağlı bir uygulama yeni bir şey bildirdi (yoklandı, bir kez kabul edildi).	`id`, `provider`, `feed`, `external_id`, `occurred_at`, `summary`, `item`
`apps.connected`	Bu çalışma alanına bir uygulama bağlandı.	`id`, `provider`, `kind`
`apps.connection_choice_set`	Bir Era’ya, iş akışına ya da sohbete bir uygulamanın hangi hesabını kullanacağı söylendi.	`subject_type`, `subject_id`, `family`, `pick`
`apps.connection_failed`	Bir sağlayıcı bir bağlantıyı reddetti.	`id`, `provider`
`apps.connection_healthy`	Bir bağlantı testi geçti.	`id`, `provider`
`apps.connection_updated`	Bir bağlantı yeniden adlandırıldı ya da yeniden yönlendirildi.	`id`, `provider`
`apps.delivered`	Giden bir webhook teslim edildi.	`webhook_id`, `event_name`
`apps.delivery_failed`	Giden bir webhook teslim edilemedi.	`webhook_id`, `event_name`, `status`
`apps.disconnected`	Bir bağlantı iptal edildi.	`id`, `provider`
`apps.paused`	Biri bir bağlantıyı duraklattı; çalışma zamanı onu atlar.	`id`, `provider`
`apps.poll_failed`	Bağlı bir uygulama bir yoklamayı reddetti.	`id`, `provider`, `feed`, `failures`, `message`
`apps.resumed`	Duraklatılmış bir bağlantı yeniden açıldı.	`id`, `provider`