quickstart manifest errors webhooks api marketplace agents surfaces

API spravochnik (v1)

Bazaviy manzil: https://platform.afai.uz (lokalda http://localhost:8100). Interaktiv versiya: GET /docs · Mashina o'qishi uchun: GET /openapi.json.

1. Umumiy qoidalar

1.1 Autentifikatsiya

Kim	Sarlavha	Qayerda ishlatiladi
Integratsiya	`Authorization: Bearer <access_token>`	`/api/v1/*`
Dasturchi	`X-Developer-Key: dvk_…`	`/api/v1/dev/*`
AFAI foydalanuvchisi	`Authorization: Bearer <console_token>`	`/console/`, `/oauth/consent`
Platforma admini	admin ilovasidan olingan `Bearer <admin_token>` yoki `X-Admin-Key`	`/admin/*`

1.2 Javob shakli

Ro'yxatlar doim bir xil:


{ "items": [ … ], "next_cursor": "run_…", "has_more": true }

Sahifalash kursor bo'yicha: ?cursor=<next_cursor>. Offset ishlatilmaydi — yangi yozuv qo'shilganda offset sahifalarni siljitib yuboradi.

1.3 Xatolar


{
  "error": {
    "code": "insufficient_scope",
    "message": "Bu amal uchun `runs:write` ruxsati kerak",
    "fix": "Integratsiya sozlamalarida shu scope'ni qo'shing…",
    "docs_url": "https://agentfather.uz/docs/errors#insufficient_scope",
    "request_id": "req_9f2c…",
    "details": { "required_scope": "runs:write" }
  }
}

To'liq ro'yxat: [ERRORS.md](ERRORS.md). Har bir javobda X-Request-Id sarlavhasi bo'ladi — qo'llab-quvvatlashga murojaat qilganda shuni yuboring.

1.4 Rate limit

Ikki daraja: installation (10 rps, burst 20) va app (50 rps, burst 100).


X-RateLimit-Limit: 20
X-RateLimit-Remaining: 17
X-RateLimit-Policy: 10.0;burst=20

429 kelganda Retry-After sarlavhasini kuting. SDK buni o'zi bajaradi.

1.5 Idempotency

Har qanday POST da Idempotency-Key: <uuid> yuborsangiz, javob 24 soat saqlanadi:

xuddi shu kalit + xuddi shu tana → saqlangan javob (Idempotency-Replayed: true);

xuddi shu kalit + boshqa tana → 409 idempotency_key_reused.

2. OAuth

`GET /oauth/authorize`

Avtorizatsiyani boshlaydi. Foydalanuvchini shu manzilga yuboring.

Parametr	Majburiy	Izoh
`client_id`	✓
`redirect_uri`	✓	Ro'yxatdan o'tgan manzil bilan to'liq mos kelishi kerak
`response_type`	✓	Faqat `code`
`code_challenge`	✓	`BASE64URL(SHA256(code_verifier))` — PKCE majburiy
`code_challenge_method`	✓	Faqat `S256`
`scope`		Bo'sh bo'lsa integratsiyaning `requested_scopes` i
`state`		CSRF himoyasi uchun — qaytganda tekshiring

Muvaffaqiyatda AFAI'ning consent sahifasiga 302 qiladi. Xato bo'lsa redirect_uri ga yubormaydi — xato JSON bo'lib qaytadi (ochiq redirect zaifligining oldi olinadi).

Rozilik Telegram ichida beriladi. Consent manzilida qo'shimcha

tg=<nonce> bo'ladi: so'rov 10 daqiqaga saqlanadi va sahifa, Telegram

sessiyasi bo'lmasa, odamni t.me/<bot>?start=oauth_<nonce> bilan

qurilmasidagi Telegram'ga uzatadi — bot esa rozilik ekranini ilovada

ochadigan tugma beradi (docs/BOT.md §4.1). Siz tomondan hech narsa

qo'shilmaydi: havola o'sha-o'sha authorize manzili.

`POST /oauth/token` · `POST /oauth/token.json`

Ikki manzil, bitta xulq — farqi faqat tana turida:

Manzil	`Content-Type`
`/oauth/token`	`application/x-www-form-urlencoded` (RFC 6749 talabi)
`/oauth/token.json`	`application/json`

Authorization sarlavhasi bu so'rovda yo'q: klient o'zini client_id va client_secret bilan tanitadi, access token esa shu so'rovdan keyin paydo bo'ladi.

Kodni almashtirish:

Maydon	Majburiy	Izoh
`grant_type`	✓	`authorization_code`
`client_id`, `client_secret`	✓	Integratsiya kalitlari
`code`	✓	Callback'ga kelgan bir martalik kod (`?code=…`, `&` gacha)
`code_verifier`	✓	PKCE juftining maxfiy yarmi — `code_challenge` emas
`redirect_uri`	—	Authorize'dagi bilan belgi-belgisiga bir xil. Integratsiyada bitta manzil bo'lsa umuman yozilmasligi mumkin

redirect_uri mos kelmasa invalid_grant qaytadi va details da ikkala qiymat ham ko'rsatiladi (expected, received) — farq ko'pincha ko'rinmaydi (oxiridagi /, nusxalangan ?code=… qismi, bo'sh joy).

Yangilash:


grant_type=refresh_token
client_id, client_secret, refresh_token


{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "…",
  "scope": "runs:read runs:write workspace:read",
  "installation_id": "ins_…",
  "workspace_id": "ws_…"
}

Rotatsiya. Har yangilashda yangi refresh token keladi va eskisi o'ladi.

Eskisini qayta ishlatish — o'g'irlik alomati: butun zanjir bekor qilinadi

va mijozga xabar beriladi. Yangi tokenni darhol saqlang.

`POST /oauth/revoke`, `POST /oauth/introspect`

RFC 7009 / RFC 7662. revoke noma'lum token uchun ham 200 qaytaradi — bu ataylab (token mavjudligini tekshirish vositasiga aylanmasin).

`GET /oauth/scopes`

Barcha scope'lar odam tilidagi izohi bilan. Consent ekrani ham shundan oladi.

Scope	Ma'nosi	Xavfli
`workspace:read`	Tashkilot nomi va sozlamalarini o'qish
`members:read`	Xodimlar ro'yxatini ko'rish
`agents:read` / `agents:write`	Agentlarni ko'rish / sozlash
`runs:read` / `runs:write`	Ishlarni o'qish / ishga tushirish
`tools:invoke`	Platforma tool'larini chaqirish	⚠
`files:read` / `files:write`	Fayllar	⚠ (write)
`webhooks:manage`	Hodisalarga obuna
`chat:read` / `chat:write`	Suhbat	⚠ (write)

:write avtomatik :read ni o'z ichiga oladi.

`GET /oauth/metadata`

RFC 8414 metadata — SDK'lar endpointlarni o'zi topadi.

3. Integratsiya API (`/api/v1`)

`GET /me`

Token kimga tegishli. Ulanishni tekshirish uchun birinchi so'rov.


{
  "installation": { "id": "ins_…", "status": "active", "scopes": [...] },
  "workspace":    { "id": "ws_…", "name": "Mijoz MChJ", "is_sandbox": false },
  "app":          { "id": "app_…", "slug": "invoice-bot" },
  "token":        { "type": "access", "expires_at": 1786710418 }
}

`GET /manifest`

O'rnatishga biriktirilgan manifest versiyasi. Mijoz eski versiyada qolgan bo'lishi mumkin — agentingiz shuni bilishi kerak.

Ishlar

Endpoint	Scope	Izoh
`POST /runs`	`runs:write`	Yaratadi va darhol ishga tushiradi
`GET /runs`	`runs:read`	`?status=`, `?limit=`, `?cursor=`
`GET /runs/{id}`	`runs:read`	Qadamlari bilan
`POST /runs/{id}/steps`	`runs:write`	Asinxron agent jonli hisobot beradi
`POST /runs/{id}/complete`	`runs:write`	`status: succeeded \	failed`
`POST /runs/{id}/cancel`	`runs:write`

Yaratish:


POST /api/v1/runs
{ "input": { "name": "Dilshod" }, "trigger": "api" }

Holatlar: queued → running → succeeded | failed | cancelled, orada awaiting_approval bo'lishi mumkin.

Tool'lar

Endpoint	Scope
`GET /tools`	— (o'rnatishga mos filtrlanadi)
`POST /tools/{name}/invoke`	`tools:invoke`


POST /api/v1/tools/notify_user/invoke
{ "arguments": { "title": "Tayyor", "body": "Hisobot yuborildi" }, "run_id": "run_…" }

Javob uch xil bo'ladi:


{ "status": "ok", "result": { … } }
{ "status": "awaiting_approval", "step_id": "stp_…", "tool": "http_fetch" }
{ "status": "rejected", "tool": "http_fetch" }

awaiting_approval — ish to'xtadi, foydalanuvchi AFAI'da tasdiqlashi kerak. Bu xavfsizlik xususiyati, xato emas: shu tufayli prompt injection agentni to'liq egallay olmaydi.

Platforma tool'lari:

Nom	Scope	Risk	Tasdiq
`workspace_info`	`workspace:read`	read	yo'q
`list_runs`	`runs:read`	read	yo'q
`notify_user`	`chat:write`	write	yo'q
`emit_event`	`webhooks:manage`	write	yo'q
`http_fetch`	`tools:invoke`	dangerous	har safar
`create_task`	`tasks:write`	write	yo'q
`delegate_task`	`tasks:write`	write	yo'q
`ask_agent`	`runs:write`	write	yo'q
`my_tasks`	`tasks:read`	read	yo'q
`ask_user`	`chat:write`	write	yo'q
`save_file`	`files:write`	write	yo'q

delegate_task — boshqa agentga vazifa berish. create_task vazifani faqat o'zingizga biriktira oladi; bu esa jamoadagi boshqa agentga topshiradi va (sukut bo'yicha) darhol ishga tushiradi.


{"agent": "sms-eskiz", "title": "120 ta raqamga xabar",
 "description": "Bazadagi mijozlarga", "start_now": true,
 "audience": "member"}

Bilib qo'yish kerak:

agent — slug yoki aniq nom. Qism moslik yo'q: "brain" hech kimga

tushmaydi (unknown_agent, javobda mavjudlar ro'yxati). Ikki agentga mos kelsa ambiguous_agent — slug yozing.

Nishon egasi allowed_callers bilan chaqiruvchilarni cheklagan bo'lsa,

tashkilot agentlararo chaqiruvni o'chirgan bo'lsa — tool_denied.

Zanjir 3 qadam (chain_too_deep) va 120 soniya

(chain_budget_exceeded) bilan cheklangan; bitta hisoblagich vazifa, savol va hisobot yo'llarida davom etadi. Chaqiruvchi o'rnatish uchun daqiqasiga ~30 agentlararo chaqiruv (rate_limited).

audience: "external" — vazifa begona mijoz matnidan kelgan; nishon

buni caller.audience da ko'radi. Ota ish tashqi bo'lsa bola ham tashqi.

Vazifa bajarilib hisobot yozilganda so'ragan agentga natija qaytadi

(task_result). Odam ochgan vazifada bu bo'lmaydi.

Nishon agentda tasks:read bo'lishi shart (agent_cannot_take_tasks).

title 300, description 8000 belgigacha.

ask_agent — boshqa agentdan javob so'rash.

delegate_task ish topshiradi va natija keyin keladi; ask_agent esa savol beradi va javobni kutadi.


{"agent": "alfabrain", "tool": "ask_brain",
 "arguments": {"question": "Kafolat muddati qancha?"},
 "audience": "external"}

Javob belgilangan holda qaytadi:


{"agent": "AlfaBrain", "tool": "ask_brain", "status": "succeeded",
 "source": "agent:alfabrain", "untrusted": true,
 "output": {"answer": "12 oy", "found": true}, "chain_depth": 1}

output 16 000 belgidan uzun bo'lsa {"truncated": true, "text": "…"}. Xatoda faqat error_code va error_message (500 belgigacha) — nishonning fix/details i sizning modelingizga ko'rsatma bo'lib tushmaydi. Bu matnni promptingizda manba sifatida o'rang, o'z gapingiz sifatida emas.

Ruxsat shartnomasi: manifestda tool e'lon qilish — «shu tashkilotdagi boshqa agentlar buni chaqirishi mumkin» degani (tool_not_offered aks holda). Argumentlar e'lon qilingan input_schema ning required va yuqori darajadagi turlari bo'yicha tekshiriladi (invalid_arguments). Nishonning o'rnatilgan versiyasidagi e'lon hisobga olinadi.

Ma'lumotga kirishni chaqirilgan agentning o'zi hal qiladi. Platforma savolni, kim so'raganini (actor — ishni boshlagan odam yoki null; installation.owner — integratsiya kimning hisobida turgani; caller — chaqiruvchi agent) va kim uchun so'ralayotganini (audience) imzolangan holda uzatadi; javob nima bo'lishini emas. external bo'lsa nishon faqat tashqariga chiqsa bo'ladigan ma'lumot beradi. Javob topilmasa found: false keladi — buni javob deb ishlatish yolg'on bo'lardi.

Har chaqiruv audit jurnaliga tushadi: agent.called yoki agent.call_denied (sababi bilan).

Egasi uchun boshqaruv (konsol):

PUT /console/settings/cross-agent {"enabled": false} — tashkilotda

agentlararo chaqiruvni butunlay o'chirish.

PUT /console/installations/{id}/policy {"allowed_callers": ["kotiba"]}

— bu agentni faqat ro'yxatdagilar chaqira oladi (slug yoki installation id). null — hamma, [] — hech kim.

Orkestrator va asosiy agent

Bosh suhbatda odam bilan sukut bo'yicha platformaning ichki agenti (PM) gaplashadi. Ikkalasi ham sozlanadi:

Endpoint	Kim	Nima qiladi
`PUT /admin/settings/pm-identity`	super-admin	PM nomi, logosi va qoidasi (`policy`)
`PUT /console/settings/primary-agent`	tashkilot	Bosh suhbatga kim javob berishi

policy — orkestratorning xatti-harakat qoidasi. U tizim promptiga qo'shiladi, lekin javob formatiga tegmaydi. Masalan: «SMS yuborishdan oldin har doim tasdiq so'ra».

primary-agent da installation_id: null — ichki orkestratorga qaytish. Boshqa agent tanlansa, bosh suhbatdagi xabarlar unga ish sifatida boradi.

Webhook obunalari

Endpoint	Izoh
`POST /webhooks`	`{url, events, description}` → javobda `secret` (bir marta)
`GET /webhooks`	Ro'yxat (sirsiz)
`DELETE /webhooks/{id}`
`POST /webhooks/{id}/test`	Sinov hodisasi — debug uchun eng foydali
`POST /webhooks/{id}/enable`	Avtomatik o'chirilganini tiklash
`GET /webhooks/{id}/deliveries`	Nima yuborildi, qanday javob keldi

Batafsil: [WEBHOOKS.md](WEBHOOKS.md).

Ish sikli (agent tomonidan)

Agent faqat run bajarmaydi — u tashkilotning ish jarayonida qatnashadi: vazifani ko'radi, tushunmasa savol beradi, hisobot yozadi, fayl qoldiradi. To'liq tavsif: [WORKFLOW.md](WORKFLOW.md).

Endpoint	Izoh
`GET /tasks`, `GET /tasks/{id}`	Menga biriktirilgan vazifalar (suhbati bilan)
`POST /tasks/{id}/progress`	Oraliq hisobot — mijoz jonli ko'radi
`POST /tasks/{id}/question`	«Tushunmadim» — vazifa `discuss` ga o'tadi, odamga bildirishnoma
`POST /tasks/{id}/report`	Yakuniy hisobot → vazifa `review` ga tushadi (hech qachon o'zi `done` bo'lmaydi)
`POST /tasks/{id}/status`	Holatni o'zgartirish (`todo → in_progress → …`)
`GET /conversations`, `GET	POST /conversations/{id}/messages`	Odam yoki PM bilan yozishma
`GET	POST /files`,` GET /files/{id}`,` DELETE /files/{id}`	Tashkilot papkalari
`GET /members`, `GET /agents`, `GET /workspace`	Kim bilan ishlayapman

Scope'lar: tasks:read / tasks:write, files:read / files:write, chat:write. O'rnatishda berilmagan scope bu yerda ham ishlamaydi.

`GET /events`

Webhook o'rnatolmaydiganlar uchun polling: ?since=<oxirgi event id>.

4. Developer API (`/api/v1/dev`)

Endpoint	Izoh
`POST /register`	Hisob + `api_key` + sandbox workspace
`GET /me`, `POST /me/rotate-key`	Profil, kalit yangilash
`POST /apps`, `GET /apps`, `GET /apps/{id}`, `PATCH /apps/{id}`	Integratsiyalar
`POST /apps/{id}/rotate-secret`	Yangi `client_secret` + barcha token bekor
`POST /apps/{id}/rotate-signing-secret`	Yangi `agsec_…`
`POST /apps/{id}/versions`	Manifest e'lon qilish
`GET /apps/{id}/versions`, `POST /apps/{id}/versions/{v}/promote`	Versiyalar
`POST /apps/{id}/test-run`	Agentni hoziroq sinash — pastga qarang
`POST /apps/{id}/sandbox-token`	O'z kodingizdan ish yaratish uchun token — pastga qarang
`POST	DELETE /sandbox/seed`	Sinov tashkilotini ma'lumot bilan to'ldirish / tozalash
`POST /apps/{id}/submit`	Marketplace moderatsiyasiga
`GET /apps/{id}/stats`, `GET /apps/{id}/logs`	Kuzatuv (faqat metama'lumot)
`POST /manifest/validate`	Autentifikatsiyasiz — CI uchun
`GET /sdk/examples`, `GET /sdk/examples/{name}`	Namuna fayllar (`main.py`, `callback.py`, `install.py`, `afai.agent.json`) — hisobsiz

Integratsiyani tahrirlash — PATCH /api/v1/dev/apps/{id}

Faqat o'zgartirmoqchi bo'lgan maydonni yuboring; yuborilmagani joyida qoladi. slug va type o'zgarmaydi.


curl -s -X PATCH $AFAI_BASE_URL/api/v1/dev/apps/$APP_ID \
  -H "X-Developer-Key: $AFAI_DEV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary": "Yangi tavsif", "requested_scopes": ["runs:write", "tasks:write"]}'

Maydon	Turi
`name`, `summary`, `description`	matn
`logo_url`, `privacy_url`, `homepage_url`, `install_url`	URL
`support_email`	email
`redirect_uris`, `requested_scopes`	ro'yxat — butunlay almashtiriladi

Noma'lum scope yuborilsa 422 va aynan qaysi biri noto'g'riligi qaytadi. requested_scopes ni kengaytirish mavjud o'rnatishlarga yangi ruxsat bermaydi — mijoz qayta rozilik berishi kerak.

Sinov ishi — POST /api/v1/dev/apps/{id}/test-run

Agentni o'z sandbox tashkilotingizga o'rnatib, bitta haqiqiy ish o'tkazadi. Bungacha o'z agentini bir marta sinash uchun dasturchi butun OAuth oqimini qo'lda bajarishi kerak edi — PKCE, mijoz sessiyasi, rozilik, token almashuvi, keyin POST /runs. Beshta qadamning birortasi ham agent kodiga aloqador emas edi.


curl -s -X POST $AFAI_BASE_URL/api/v1/dev/apps/$APP_ID/test-run \
  -H "X-Developer-Key: $AFAI_DEV_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"a": 12, "b": 5, "op": "+"}}'


{
  "installation_id": "ins_…",
  "workspace_id": "ws_…",
  "agent": { "version": "1.0.0", "runtime_type": "webhook",
             "endpoint": "https://sizning-agent.uz" },
  "run": {
    "id": "run_…", "status": "succeeded", "duration_ms": 41,
    "output": { "result": 17 },
    "steps": [ { "seq": 1, "type": "message", "output": {"text": "…"} } ]
  }
}

Bilib qo'yish kerak bo'lganlar:

Ish haqiqiy: o'sha dispatcher, o'sha X-AFAI-Signature imzosi, o'sha

qadamlar va xatolar. Simulyator emas — bu yerda ishlagan narsa mijozda ham ishlaydi.

Agent yiqilsa javob baribir 200 bo'ladi, ichida run.status: "failed"

va error_code. Ya'ni «sinov yashil» bo'lib qolmaydi.

agent.endpoint — so'rov aynan qayerga ketgani. «Hech nima kelmadi»

holatida birinchi savol shu.

Manifest bo'lmasa 409 no_manifest. Moderatsiya shart emas: draft

agentni ham sinash mumkin.

O'rnatish qayta ishlatiladi — har sinovda yangi yozuv yasalmaydi, lekin

har safar eng yangi manifestga ko'chiriladi.

Chastota cheklangan (dasturchi hisobi bo'yicha, daqiqada ~6 ta): bu

endpoint platformani ixtiyoriy manzilga so'rov yuborishga majbur qiladi.

Sinov ishlari statistikaga qo'shilmaydi: GET /apps/{id}/stats da

installations va runs faqat mijoznikini sanaydi, sinov raqamlari esa alohida sandbox blokida turadi. Aks holda o'z sinovingiz o'sish bo'lib ko'rinardi.

Sinov tokeni — POST /api/v1/dev/apps/{id}/sandbox-token

test-run da ishni platformaning o'zi yaratadi. Ertami-kechmi siz uni o'z kodingizdan yaratishni sinashingiz kerak: SDK, navbat, xatolarni qayta urinish. Buning uchun access_token kerak, token esa OAuth orqali beriladi — rozilikni faqat mijoz sessiyasi bera oladi, mijoz sessiyasi esa AFAI ilovasida turadi. Natijada dasturchilar o'z agentini sinash uchun tokenni brauzer konsolidan (localStorage) qidirib olishga majbur bo'lgan.


curl -s -X POST $AFAI_BASE_URL/api/v1/dev/apps/$APP_ID/sandbox-token \
  -H "X-Developer-Key: $AFAI_DEV_KEY"


{
  "access_token": "eyJhbGciOi…",
  "token_type": "Bearer",
  "expires_in": 7200,
  "refresh_token": "…",
  "scope": "runs:write workspace:read",
  "installation_id": "ins_…",
  "workspace_id": "ws_…",
  "agent_version": "1.0.0"
}

Token o'z app'ingiz va o'z sinov tashkilotingiz uchun — ya'ni

test-run allaqachon yasab qo'ygan o'rnatishga. Mijoz tashkilotiga bu yo'l bilan kirib bo'lmaydi; u yerga faqat mijozning roziligi orqali kiriladi (7-bo'lim).

Token oddiy access_token: o'sha imzo, o'sha muddat, o'sha

scope'lar. Shu bilan yozilgan kod mijoz tokenida ham o'zgarishsiz ishlaydi — shuning uchun soddalashtirilgan «sinov rejimi» qo'yilmadi.

Manifest bo'lmasa 409 no_manifest: token o'rnatishga beriladi,

o'rnatish esa versiyaga bog'lanadi.

Har chaqiruvda yangi token keladi, o'rnatish esa o'sha qoladi.

Portalda bu «Sinov» bo'limidagi «Sinov tokeni» tugmasi.

Sinov ma'lumoti — POST /api/v1/dev/sandbox/seed

Sinov tashkiloti bo'sh ochiladi, va bo'sh tashkilotda agentni sinab bo'lmaydi. Bu buyruq unga haqiqiy shakldagi ma'lumot qo'yadi: vazifalar, bajarilgan ishlar, fayllar, bildirishnomalar. Jumladan «Kontaktlar» papkasida telefon raqamlari bo'lgan Mijozlar ro'yxati.csv — qo'ng'iroq qiladigan agentni sinash uchun.


curl -s -X POST $AFAI_BASE_URL/api/v1/dev/sandbox/seed \
  -H "X-Developer-Key: $AFAI_DEV_KEY"
# → {"tasks": 8, "runs": 12, "files": 6, "notifications": 4, ...}

Idempotent: qayta chaqirilsa avval eskisini o'chiradi. DELETE bilan qaytarib olinadi. Faqat shu buyruq qo'ygan yozuvlarga tegiladi — o'zingiz qo'shgan ma'lumot joyida qoladi.

Marketplace bo'sh bo'lsa 409 marketplace_empty keladi (o'z platformangizni ko'targan holat) — nima qilish kerakligi javobning fix maydonida.

So'rovlar va yozishma:

Endpoint	Izoh
`GET /api/v1/dev/requests`	Mijozlar so'ragan agentlar doskasi
`POST /api/v1/dev/requests/{id}/claim`	«Men qilaman»
`GET	POST /api/v1/dev/verification`	Tasdiqlangan nishoni uchun ariza
`GET	POST /api/v1/dev/apps/{id}/messages`	Moderator bilan yozishma

Otzivlar — baho faqat mijozdan keladi, dasturchi uni o'zgartira olmaydi, javob yozishi mumkin:

Endpoint	Izoh
`GET /api/v1/dev/reviews`	Hamma agentim bo'yicha; `?unanswered=true` — javob kutayotganlari
`GET /api/v1/dev/apps/{id}/reviews`	Bitta agent: o'rtacha, yulduzlar taqsimoti, ro'yxat
`POST /api/v1/dev/reviews/{id}/reply`	Otzivga javob (mijozga bildirishnoma boradi)

5. Console API (`/console`)

Mijoz tomonidagi ekranlar uchun. Integratsiyalar bu yerga kirmaydi.

Endpoint	Izoh
`POST /session`	Lokal ishlab chiqishda sessiya (prodda yopiq — `console_provisioning_disabled`)
`POST /bot/webapp-auth`	Telegram Mini App `initData` si → sessiya
`POST /bot/widget-auth`	Brauzerda Telegram Login Widget javobi → sessiya
`GET /bot/info`	Kirish tugmasi uchun bot @nomi
`GET /me`	Foydalanuvchi + tashkilot + admin taqiqlari
`GET /marketplace`	O'rnatish mumkin bo'lgan agentlar
`GET /install/{slug}`	«O'rnatish» havolasi parametrlari
`GET /installations`, `DELETE /installations/{id}`	O'rnatilganlar
`GET	PUT /installations/{id}/settings`	Manifest `config` i bo'yicha forma
`PUT /installations/{id}/policy`	`denied_tools` — admin taqiqi
`POST /installations/{id}/surface-token`	iframe uchun 5 daqiqalik token
`GET /runs`, `GET /runs/{id}`	Ishlar
`POST /runs/{id}/steps/{step}/decision`	Xavfli amalni tasdiqlash
`GET /audit`	Audit jurnali (admin)

Sessiya qayerdan keladi. Mijoz hisobi Telegram akkauntiga bog'langan,

shuning uchun console tokenni ham Telegram beradi: ilova ichida initData

(/bot/webapp-auth), brauzerda Login Widget (/bot/widget-auth). Ikkisi

ham imzo bilan ishlaydi va bir xil hisobga olib keladi. POST /session

faqat CONSOLE_AUTO_PROVISION=true bo'lgan muhitda ishlaydi — prodda

ataylab yopiq.

Dasturchi sifatida bu sizga kerak emas: agentni sinash uchun

POST /api/v1/dev/apps/{id}/sandbox-token bor (4-bo'lim). Console

sessiyasi mijozning sessiyasi.

Ish sikli (Workspace, Agent Flux, Folders, Dashboard ekranlari):

Endpoint	Izoh
`GET	POST /tasks`,` GET	PATCH /tasks/{id}`	Kanban
`POST /tasks/{id}/run`	Vazifani agentga topshirish (to'liq kontekst + suhbat tarixi bilan)
`POST /tasks/{id}/messages`	Agentning savoliga javob
`GET /conversations`, `GET	POST /conversations/{id}/messages`	Agent bilan chat
`GET	POST /files`,` GET /files/{id}/download`,` DELETE /files/{id}`	Papkalar
`GET /notifications`, `POST /notifications/read`	Bildirishnomalar
`GET /analytics`	Dashboard ko'rsatkichlari
`GET /agents`	Vazifa biriktirish mumkin bo'lgan agentlar

Telegram (to'liq tavsif: [TELEGRAM.md](TELEGRAM.md)):

Endpoint	Izoh
`GET /telegram/accounts` + `/accounts/bot` · `/accounts/user`	Ulanish (bot yoki shaxsiy akkaunt)
`GET /telegram/chats`, `GET	POST /telegram/chats/{id}/messages`	Dialoglar va yozishma
`POST /telegram/messages/{id}/approve`	Agent loyihasini tasdiqlab yuborish

So'rovlar:

Endpoint	Izoh
`GET	POST /agent-requests`	Wishlist: «shunday agent kerak»
`POST /agent-requests/{id}/vote`	Ovoz berish
`POST /abuse-reports`	Agent ustidan shikoyat

Otzivlar — yozish huquqi faqat agentni o'rnatgan tashkilotda, bitta tashkilot bitta otziv qoldiradi (qayta yuborilsa tahrirlanadi):

Endpoint	Izoh
`GET /console/apps/{id}/reviews`	O'rtacha, taqsimot, ro'yxat + `mine`
`PUT /console/apps/{id}/review`	`rating` 1..5 + ixtiyoriy `text`
`DELETE /console/apps/{id}/review`	O'z otzivini olib tashlash

6. Admin API (`/admin`)

Platforma xodimi uchun: moderatsiya, akkauntlar, to'xtatish, global taqiqlar.

Bu alohida ilova (admin/, port 8090) uchun: admin o'z email/paroli bilan POST /admin/auth/login orqali kiradi. Mijoz sessiyasi bu yerda ishlamaydi. Rollar: superadmin (hammasi) va moderator (faqat moderatsiya + o'qish). To'liq tavsif: [ADMIN.md](ADMIN.md).

Endpoint	Izoh
`POST /admin/auth/login`	Email + parol → admin tokeni (8 soat)
`GET /admin/admins` + CRUD	Admin hisoblari (superadmin)
`GET /admin/me`, `GET /admin/overview`	Kim ekanim, umumiy ko'rsatkichlar
`GET /admin/review`	Moderatsiya navbati (checklist bilan)
`POST /admin/apps/{id}/approve` / `reject`	Moderatsiya qarori
`POST /admin/apps/{id}/suspend` / `unsuspend`	Kill switch
`GET /admin/apps`, `GET /admin/apps/{id}`	Barcha integratsiyalar
`GET /admin/developers` + `verify` / `block` / `unblock`	Dasturchilar
`GET /admin/workspaces` + `status`	Tashkilotlar
`POST /admin/installations/{id}/status`	O'rnatish holati
`POST /admin/apps/{id}/versions/{vid}/approve` / `reject`	Versiya moderatsiyasi
`GET /admin/apps/{id}/checks`, `POST /admin/apps/{id}/test-install`	Avtomatik tekshiruv, sandbox sinovi
`POST /admin/apps/{id}/claim` / `delist` / `curation`	Navbat, delist, `featured`
`GET /admin/requests`, `/admin/agent-requests/{id}/status`	Wishlist
`POST /admin/abuse-reports/{id}/resolve`, `/admin/verifications/{id}/decide`	Shikoyat, verifikatsiya
`GET	POST /admin/apps/{id}/messages`	Dasturchi bilan yozishma
`GET /admin/reviews`, `POST /admin/reviews/{id}/hide`	Otzivlar; yashirish o'chirish emas — qaytarish mumkin
`GET /admin/runs`, `GET /admin/audit`, `GET /admin/health`	Kuzatuv (`limit` + `offset`)
`GET /admin/metrics`, `GET /admin/export/{dataset}`	Kunlik dinamika, CSV
`GET /admin/settings`, `PUT /admin/settings/denied-tools`	Global taqiq

Ruxsat ierarxiyasi (kuchli → kuchsiz):


platforma taqiqi → scope → tashkilot taqiqi → o'rnatish taqiqi

7. Agent runtime protokoli

Platforma agentga imzolangan so'rov yuboradi:


POST https://sizning-agent/afai
X-AFAI-Signature: t=1786710418,v1=5f0b…
X-AFAI-Event: run.execute
Content-Type: application/json

{
  "type": "run.execute",
  "run": { "id": "run_…", "input": {…}, "trigger": "manual" },
  "agent": { "id": "acme.invoice-bot", "version": "1.2.0" },
  "installation": {
    "id": "ins_…", "workspace_id": "ws_…",
    "scopes": ["runs:write"],
    "settings": { "api_key": "ochilgan qiymat" }
  },
  "callback": { "base_url": "https://platform.afai.uz/api/v1", "token": "eyJ…", "expires_in": 900 }
}

Javob variantlari:


200 { "status": "succeeded", "output": {…}, "steps": [ … ], "cost_units": 1.5 }
200 { "status": "failed", "error_code": "quota_exceeded", "error_message": "…" }
202                                  // keyinroq /runs/{id}/complete chaqiraman

Imzoni albatta tekshiring — SDK buni o'zi qiladi ([WEBHOOKS.md](WEBHOOKS.md) §3).

API spravochnik (v1)

1. Umumiy qoidalar

1.1 Autentifikatsiya

1.2 Javob shakli

1.3 Xatolar

1.4 Rate limit

1.5 Idempotency

2. OAuth

GET /oauth/authorize

POST /oauth/token · POST /oauth/token.json

POST /oauth/revoke, POST /oauth/introspect

GET /oauth/scopes

GET /oauth/metadata

3. Integratsiya API (/api/v1)

GET /me

GET /manifest