codai docs
Referință APIGateway

Declanșatoare

Webhook-uri care transformă evenimentele din GitHub, Sentry, monitorizare sau surse proprii în sesiuni de agent, plus inbox-ul de notificări.

Un declanșator (trigger) este un webhook de intrare semnat, legat de contul tău. Fiecare livrare e verificată cu secretul propriu al declanșatorului, transformată într-o fișă de eveniment, trecută prin politica declanșatorului (filtre, buget, limită de rată, deduplicare) și apoi deschide o sesiune, se adaugă la una deja deschisă sau doar publică o notificare.

Semnarea livrărilor generice

Expeditorii proprii semnează cu schema codai:

x-codai-signature: t=<secunde unix>,v1=<hex HMAC-SHA256(secret, "<t>.<corp brut>")>
x-codai-delivery: <id-ul livrării tale>
  • HMAC-ul acoperă marcajul de timp, un . literal și corpul brut al cererii, octet cu octet — semnează înainte de orice reserializare.
  • t trebuie să fie la cel mult 5 minute de ceasul gateway-ului; marcajele mai vechi sau din viitor sunt respinse cu stale_timestamp.
  • x-codai-delivery este cheia de idempotență: un id de livrare repetat se înregistrează o singură dată. Fără el, gateway-ul derivă un id din t și dintr-un hash al corpului.
  • Sursele GitHub (X-Hub-Signature-256) și Sentry (Sentry-Hook-Signature) folosesc în schimb semnăturile lor native.

Căi de intrare

Câmpul ingress din politica declanșatorului stabilește unde sunt acceptate livrările:

  • public (implicit) — endpoint-ul expus pe internet POST /v1/hooks/{id}.
  • local — surse doar din rețeaua locală. URL-ul public răspunde 404; livrările ajung prin daemonul codaid sau prin brokerul aplicației desktop din rețeaua ta, care le transmit mai departe cu aceeași verificare de semnătură.
  • both — oricare dintre cele două.

Folosește rotate-secret ca să generezi un secret nou sau PUT …/secret ca să setezi secretul cu care semnează deja un serviciu terț. POST …/test trimite o livrare de probă semnată prin tot fluxul.

GET
/v1/triggers

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Trigger-ele apelantului.

application/json
  1. response
data*array<>
sources*array<>
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/triggers'
Exemplu de răspuns
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "source": "github",      "enabled": true,      "policy": {        "mode": "notify",        "smart": {          "assistedAt": "info",          "autopilotAt": "info",          "keywords": {            "property1": "notify",            "property2": "notify"          }        },        "subjects": [          "string"        ],        "minSeverity": "info",        "permissions": "read",        "quietHours": {          "from": "string",          "to": "string",          "tz": "Europe/Bucharest"        },        "budgetMicroUsdPerEvent": 2000000,        "budgetMicroUsdPerDay": 10000000,        "maxSessionsPerHour": 6,        "dedupeWindowMin": 1440,        "promptTemplate": "string",        "skill": "string",        "target": {          "kind": "any",          "id": "string"        },        "ttlMin": 240      },      "hook_url": "http://example.com",      "last_event_at": "2019-08-24T14:15:22Z",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "sources": [    "github"  ]}
POST
/v1/triggers

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json
  1. body
name*string
Lungime1 <= length <= 120
source*TriggerSource

Cum sunt autentificate și normalizate livrările (vezi POST /v1/hooks/{id}).

Valoare din"github""sentry""gcp""generic""form""manual"
policy?

TriggerPolicy parțială; cheile omise primesc valorile implicite, valorile invalide dau 400.

enabled?boolean
Implicittrue

Corpul răspunsului

Creat; secret este afișat o singură dată.

application/json
  1. response
id*string
Formatuuid
name*string
source*TriggerSource

Cum sunt autentificate și normalizate livrările (vezi POST /v1/hooks/{id}).

Valoare din"github""sentry""gcp""generic""form""manual"
enabled*boolean
policy*

Politica trigger-ului cu toate valorile implicite completate (așa cum o returnează API-ul).

hook_url*string

Unde postează expeditorul, https://api.codai.ro/v1/hooks/<id> în producție.

Formaturi
last_event_at*|
Formatdate-time
created_at*string
Formatdate-time
secret*string

Secret de semnare, prefix whsec_. Afișat doar în acest răspuns.

Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/triggers' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "source": "github"}'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "source": "github",  "enabled": true,  "policy": {    "mode": "notify",    "smart": {      "assistedAt": "info",      "autopilotAt": "info",      "keywords": {        "property1": "notify",        "property2": "notify"      }    },    "subjects": [      "string"    ],    "minSeverity": "info",    "permissions": "read",    "quietHours": {      "from": "string",      "to": "string",      "tz": "Europe/Bucharest"    },    "budgetMicroUsdPerEvent": 2000000,    "budgetMicroUsdPerDay": 10000000,    "maxSessionsPerHour": 6,    "dedupeWindowMin": 1440,    "promptTemplate": "string",    "skill": "string",    "target": {      "kind": "any",      "id": "string"    },    "ttlMin": 240  },  "hook_url": "http://example.com",  "last_event_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z",  "secret": "string"}
PATCH
/v1/triggers/{id}

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul trigger-ului. Un id malformat, necunoscut sau străin primește 404.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json
  1. body
name?string
Lungime1 <= length <= 120
policy?

Înlocuiește politica stocată (nu se combină); cheile omise primesc valorile implicite.

enabled?boolean

Corpul răspunsului

Trigger-ul actualizat.

application/json
  1. response
id*string
Formatuuid
name*string
source*TriggerSource

Cum sunt autentificate și normalizate livrările (vezi POST /v1/hooks/{id}).

Valoare din"github""sentry""gcp""generic""form""manual"
enabled*boolean
policy*

Politica trigger-ului cu toate valorile implicite completate (așa cum o returnează API-ul).

hook_url*string

Unde postează expeditorul, https://api.codai.ro/v1/hooks/<id> în producție.

Formaturi
last_event_at*|
Formatdate-time
created_at*string
Formatdate-time
Exemplu de cerere
curl -X PATCH 'https://ai.codai.ro/v1/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "source": "github",  "enabled": true,  "policy": {    "mode": "notify",    "smart": {      "assistedAt": "info",      "autopilotAt": "info",      "keywords": {        "property1": "notify",        "property2": "notify"      }    },    "subjects": [      "string"    ],    "minSeverity": "info",    "permissions": "read",    "quietHours": {      "from": "string",      "to": "string",      "tz": "Europe/Bucharest"    },    "budgetMicroUsdPerEvent": 2000000,    "budgetMicroUsdPerDay": 10000000,    "maxSessionsPerHour": 6,    "dedupeWindowMin": 1440,    "promptTemplate": "string",    "skill": "string",    "target": {      "kind": "any",      "id": "string"    },    "ttlMin": 240  },  "hook_url": "http://example.com",  "last_event_at": "2019-08-24T14:15:22Z",  "created_at": "2019-08-24T14:15:22Z"}
DELETE
/v1/triggers/{id}

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul trigger-ului. Un id malformat, necunoscut sau străin primește 404.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Șters.

application/json
  1. response
id*string
Formatuuid
deleted*true
Valoare dintrue
Exemplu de cerere
curl -X DELETE 'https://ai.codai.ro/v1/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "deleted": true}
POST
/v1/triggers/{id}/rotate-secret

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul trigger-ului. Un id malformat, necunoscut sau străin primește 404.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Secretul nou (afișat o singură dată).

application/json
  1. response
id*string
Formatuuid
secret*string

Secret de semnare nou, prefix whsec_. Nu mai este returnat niciodată.

Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08/rotate-secret'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "secret": "string"}
PUT
/v1/triggers/{id}/secret

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul trigger-ului. Un id malformat, necunoscut sau străin primește 404.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json
  1. body
secret*string
Lungime16 <= length <= 512

Corpul răspunsului

Secret înlocuit.

application/json
  1. response
id*string
Formatuuid
replaced*boolean
Exemplu de cerere
curl -X PUT 'https://ai.codai.ro/v1/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08/secret' \  -H 'Content-Type: application/json' \  -d '{  "secret": "stringstringstri"}'
Exemplu de răspuns
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "replaced": true}
POST
/v1/triggers/{id}/test

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul trigger-ului. Un id malformat, necunoscut sau străin primește 404.

Formatuuid

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json
  1. body
title?string
Lungimelength <= 200
message?string
Lungimelength <= 4000
severity?TriggerSeverity
Valoare din"info""low""medium""high""critical"
url?string
Formaturi
subject?string
Lungimelength <= 200

Corpul răspunsului

Evenimentul înregistrat și decizia politicii.

application/json
  1. response
event_id*integer

Id-ul livrării înregistrate (vezi GET /v1/triggers/{id}/events).

decision*

Ce a decis politica pentru un eveniment și de ce (reason este afișat pe sesiune).

session_id*|

Sesiunea pornită sau completată; null pentru deciziile notify/ignore.

Formatuuid
card*

O livrare normalizată într-o formă unică, independentă de sursă.

Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08/test' \  -H 'Content-Type: application/json' \  -d '{}'
Exemplu de răspuns
{  "event_id": 0,  "decision": {    "action": "ignore",    "reason": "string",    "mode": "notify",    "wanted": "notify",    "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"  },  "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82",  "card": {    "source": "github",    "kind": "string",    "title": "string",    "summary": "string",    "severity": "info",    "url": "string",    "subject": "string",    "dedupeKey": "string",    "labels": [      "string"    ],    "resolved": true  }}
GET
/v1/triggers/{id}/events

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*string

UUID-ul trigger-ului. Un id malformat, necunoscut sau străin primește 404.

Formatuuid

Parametri query

limit?integer

Dimensiunea paginii, limitată la 1–200; orice valoare nenumerică revine la 50.

Interval1 <= value <= 200
Implicit50

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Livrări ordonate descrescător după receivedAt.

application/json
  1. response
data*array<>
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/triggers/497f6eca-6276-4993-bfeb-53cbbbba6f08/events'
Exemplu de răspuns
{  "data": [    {      "id": 0,      "deliveryId": "string",      "status": "received",      "card": {        "source": "github",        "kind": "string",        "title": "string",        "summary": "string",        "severity": "info",        "url": "string",        "subject": "string",        "dedupeKey": "string",        "labels": [          "string"        ],        "resolved": true      },      "decision": {        "action": "ignore",        "reason": "string",        "mode": "notify",        "wanted": "notify",        "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459"      },      "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",      "attempts": 0,      "error": "string",      "receivedAt": "2019-08-24T14:15:22Z",      "processedAt": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/hooks/{id}

Parametri de cale

id*string

UUID-ul trigger-ului (ultimul segment din hook_url).

Formatuuid

Parametri query

token?string

Doar sursa gcp: secretul trigger-ului, când expeditorul nu poate seta un header Authorization.

Parametri header

x-hub-signature-256?string

Sursa github: sha256= urmat de HMAC-SHA256 hex al corpului brut.

x-github-delivery?string

Sursa github (obligatoriu acolo): GUID-ul livrării, folosit drept cheie de idempotență.

x-github-event?string

Sursa github: tipul evenimentului (issues, pull_request, workflow_run, …).

sentry-hook-signature?string

Sursa sentry: HMAC-SHA256 hex al corpului brut, cu secretul trigger-ului.

sentry-hook-resource?string

Sursa sentry: resursa la care se referă evenimentul (issue, event_alert, metric_alert, …).

request-id?string

Sursa sentry: id-ul livrării, folosit drept cheie de idempotență.

x-codai-signature?string

Sursele generic / form / manual: t=<unix>,v1=<HMAC-SHA256 hex al "<t>.<corp brut>">.

x-codai-delivery?string

Sursele generic / form / manual: cheie de idempotență opțională pentru livrare.

Corpul cererii

application/json
  1. body

Payload-ul JSON propriu al expeditorului. Expeditorii generic / form / manual pot folosi title, message, severity (info…critical), url, subject și kind pentru a modela cardul evenimentului.

[key: string]?any

Corpul răspunsului

Acceptat (înregistrat; procesat după răspuns).

application/json
  1. response
accepted*true
Valoare dintrue
duplicate*boolean

true când acest id de livrare a fost deja înregistrat; nu mai este procesat.

event_id*integer

Id-ul livrării înregistrate.

Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/hooks/497f6eca-6276-4993-bfeb-53cbbbba6f08' \  -H 'Content-Type: application/json' \  -d '{}'
Exemplu de răspuns
{  "accepted": true,  "duplicate": true,  "event_id": 0}
GET
/v1/notifications

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri query

unread?"1"

1 pentru a returna doar notificările necitite.

Valoare din"1"
limit?integer

Dimensiunea paginii, limitată la 1–200; orice valoare nenumerică revine la 50.

Interval1 <= value <= 200
Implicit50

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Notificări ordonate descrescător după createdAt.

application/json
  1. response
data*array<>
Exemplu de cerere
curl -X GET 'https://ai.codai.ro/v1/notifications'
Exemplu de răspuns
{  "data": [    {      "id": 0,      "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",      "kind": "string",      "severity": "info",      "title": "string",      "body": "string",      "url": "string",      "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",      "triggerEventId": 0,      "readAt": "2019-08-24T14:15:22Z",      "createdAt": "2019-08-24T14:15:22Z"    }  ]}
POST
/v1/notifications/read

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json
  1. body
ids?array<>
Elementeitems <= 500

Corpul răspunsului

Câte notificări au fost actualizate.

application/json
  1. response
read*integer
Interval0 <= value
Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/notifications/read' \  -H 'Content-Type: application/json' \  -d '{}'
Exemplu de răspuns
{  "read": 0}
DELETE
/v1/notifications/{id}

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri de cale

id*integer
Interval1 <= value

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul răspunsului

Câte notificări au fost șterse (0 sau 1).

application/json
  1. response
deleted*integer
Interval0 <= value
Exemplu de cerere
curl -X DELETE 'https://ai.codai.ro/v1/notifications/1'
Exemplu de răspuns
{  "deleted": 0}
POST
/v1/notifications/delete

Autorizare

bearerAuth
headerAutorizareBearer <codai_…>

O cheie API codai (prefix codai_). Tokenurile efemere de la POST /v1/tokens sunt acceptate doar de suprafețele media potrivite scope-ului lor (/v1/realtime, /v1/audio/*, /v1/embeddings).

Parametri header

x-request-id?string

Id de corelare ales de client; e returnat ca x-codai-trace-id și persistat pe rândul de usage.

Lungimelength <= 128

Corpul cererii

application/json
  1. body
ids*array<>
Elemente1 <= items <= 200

Corpul răspunsului

Câte notificări au fost șterse.

application/json
  1. response
deleted*integer
Interval0 <= value
Exemplu de cerere
curl -X POST 'https://ai.codai.ro/v1/notifications/delete' \  -H 'Content-Type: application/json' \  -d '{  "ids": [    1  ]}'
Exemplu de răspuns
{  "deleted": 0}

Ultima actualizare:

Task-uri

Facturare pe rezultat: listezi task-urile deschise de cererile tale și confirmi sau respingi rezultatul lor.

Prompturi în așteptare

Prompturi gata de lipit pe care agenții (sau tu) le lasă pentru un chat viitor — predări, continuări programate — cu mementouri și lansare dintr-un clic pe un dispozitiv.

Pe această pagină

Semnarea livrărilor genericeCăi de intrare