Yapay Zeka Koşuları

Yapay zeka özellikleri önceden tanımlanmış yeteneklerdir (ör. özetleme, analiz, koçluk). Her çağrı, yürütmeyi adım adım izleyen bir çalıştırma oluşturur.

Sözleşme güncellemesi (2026-04): POST isteğinin gövdesi, canlı API ile eşleşecek şekilde düzeltildi. 'Giriş' nesnesi, 'agentId' ve 'workspaceId' alanları kabul edilmez. Bunun yerine "mesajlar" dizisini kullanın.

Orkestrasyon Çözüm Yolunu Çalıştır

Mevcut özellik anahtarlarını keşfetmek için kataloğu (GET /ai/features) listeleyin.
Kullanıcı istemini içeren bir 'messages' dizisiyle bir çalıştırma ('POST /ai/features/:featureKey/runs') oluşturun.
Çalıştırma durumunu 'GET /ai/runs/:runId' veya 'GET /ai/runs/:runId/steps' yoluyla izleyin ve artımlı olayları 'GET /ai/runs/:runId/stream' aracılığıyla yayınlayın.
Bir çalıştırma durduğunda iptal edin (POST /ai/runs/:runId/cancel) veya yeniden deneyin (POST /ai/runs/:runId/retry) ve ardından çalıştırma tamamlandığında son 'çıkış' alanını yakalayın.

javascript

const orchestrateFeature = async () => {
  const featureRes = await fetch(`${BASE_URL}/ai/features`, {
    headers: { Authorization: `Bearer ${TOKEN}` },
  });
  const feature = (await featureRes.json()).data.find(
    (f) => f.key === "chain-coach"
  );

  const runRes = await fetch(
    `${BASE_URL}/ai/features/${feature.key}/runs`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${TOKEN}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        messages: [
          { role: "user", content: "Help me maintain my daily vocabulary completion history" }
        ],
      }),
    }
  );
  const run = (await runRes.json()).data;
  const stream = new EventSource(
    `${BASE_URL}/ai/runs/${run.id}/stream`,
    { headers: { Authorization: `Bearer ${TOKEN}` } }
  );
  stream.onmessage = (event) => console.log(JSON.parse(event.data));
};

Uç noktalar

Method	Path	Description	Auth	Rate Limit
GET	`/ai/features`	List AI feature catalog	JWT + Entitlement	60/min
POST	`/ai/features/:featureKey/runs`	Create a run for a feature	JWT + Entitlement	20/min
GET	`/ai/runs`	List runs	JWT + Entitlement	60/min
GET	`/ai/runs/:runId`	Get a run	JWT + Entitlement	60/min
GET	`/ai/runs/:runId/steps`	List steps of a run	JWT + Entitlement	60/min
GET	`/ai/runs/:runId/stream`	SSE stream for a run	JWT + Entitlement	20/min
POST	`/ai/runs/:runId/cancel`	Cancel a running run	JWT + Entitlement	30/min
POST	`/ai/runs/:runId/retry`	Retry a failed run	JWT + Entitlement	10/min
POST	`/ai/runs/:runId/resume`	Kurtarılabilir kesintili bir çalıştırmayı sürdür	JWT + Entitlement	—

GET /ai/features

Katalogda mevcut tüm AI özelliklerini listeleyin.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 60/dak

Rica etmek

Yol veya sorgu parametresi yok. Talep organı yok.

Cevap

Yanıt Örneği

json

{
  "data": [
    {
      "key": "chain-coach",
      "name": "Chain Coach",
      "description": "AI-powered coaching for maintaining chain run history",
      "category": "productivity",
      "inputSchema": {
        "chainId": "string",
        "context": "string"
      }
    },
    {
      "key": "bit-decomposer",
      "name": "Bit Decomposer",
      "description": "Break down complex bits into smaller actionable items",
      "category": "productivity",
      "inputSchema": {
        "bitId": "string"
      }
    }
  ]
}

Yanıt Alanları

Field	Type	Description
`key`	string	Feature identifier
`name`	string	Display name
`description`	string	Feature description
`category`	string	Feature category
`inputSchema`	object	Expected input fields

Kod Örnekleri

JavaScriptPython

javascript

const res = await fetch(`${BASE_URL}/ai/features`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

python

import requests

res = requests.get(
    f"{BASE_URL}/ai/features",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

POST /ai/runs/:runId/resume

Kurtarılabilir bir durumda duran çalıştırmayı sürdürür. İstek gövdesi yoktur.

Başarılı istek 200 OK ile çalıştırma id değerini, yeni status değerini ve replayed boolean alanını döndürür. Çalıştırma çağıranın izin verilen kapsamı dışındaysa API 403, çalıştırma kurtarılabilir durumda değilse 409 conversation_run_not_resumable döndürür.

POST /ai/features/:featureKey/runs

Belirtilen AI özelliği için yeni bir çalıştırma oluşturun.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 20/dak

Abonelik gereklidir. Yapay zeka özelliği çalıştırmaları oluşturmak için aktif bir ücretli abonelik gerekir. Kredi bakiyesi tek başına yetersizdir. Geçerli bir ücretli aboneliği olmayan istekler, { "code": "subscription_inactive" } ile 403 Forbidden alır.

Rica etmek

Field	Type	Required	Constraints	Description
`messages`	array	Yes	1–50 items	Conversation messages to send
`messages[].role`	string	Yes	`"user"` or `"assistant"`	Role of the message author
`messages[].content`	string	Yes	Non-empty	Message content
`temperature`	number	No	0–2	Sampling temperature
`maxOutputTokens`	number	No	1–200,000	Maximum tokens in the response
`idempotencyKey`	string	No	Max 256 chars	Prevents duplicate runs on retry
`modelId`	string	No	UUID	Override the default model

Cevap

Yanıt Örneği

json

{
  "data": {
    "id": "cm5run001",
    "featureKey": "chain-coach",
    "status": "queued",
    "output": null,
    "startedAt": null,
    "completedAt": null,
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Yanıt Alanları

Field	Type	Description
`id`	string	Run ID
`featureKey`	string	Feature that triggered the run
`status`	string	`queued`, `running`, `completed`, `failed`, `cancelled`
`output`	object \| null	Run output
`startedAt`	string \| null	ISO 8601
`completedAt`	string \| null	ISO 8601 or null
`createdAt`	string	ISO 8601

Kod Örnekleri

JavaScriptPython

javascript

const res = await fetch(`${BASE_URL}/ai/features/chain-coach/runs`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    messages: [
      {
        role: "user",
        content: "I have been struggling to maintain my daily vocabulary practice completion history",
      },
    ],
  }),
});
const { data } = await res.json();

python

import requests

res = requests.post(
    f"{BASE_URL}/ai/features/chain-coach/runs",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "messages": [
            {
                "role": "user",
                "content": "I have been struggling to maintain my daily vocabulary practice completion history",
            }
        ]
    },
)
data = res.json()["data"]

GET /ai/runs

İsteğe bağlı filtrelerle tüm çalıştırmaları listeleyin.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 60/dak

Rica etmek

Parameter	Type	Required	Description
`agentId`	string	No	Filter by agent
`workspaceId`	string	No	Filter by workspace
`featureKey`	string	No	Filter by feature
`status`	string	No	Filter by status: `queued`, `running`, `completed`, `failed`, `cancelled`
`limit`	number	No	Items per page
`offset`	number	No	Pagination offset

Cevap

Yanıt Örneği

json

{
  "data": [
    {
      "id": "cm5run001",
      "featureKey": "chain-coach",
      "status": "completed",
      "startedAt": "2026-03-17T10:00:00.000Z",
      "completedAt": "2026-03-17T10:00:12.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 10,
    "offset": 0
  }
}

Yanıt Alanları

Field	Type	Description
`id`	string	Run ID
`featureKey`	string	Feature that triggered the run
`status`	string	`queued`, `running`, `completed`, `failed`, `cancelled`
`startedAt`	string	ISO 8601
`completedAt`	string \| null	ISO 8601 or null

Kod Örnekleri

JavaScriptPython

javascript

const params = new URLSearchParams({
  featureKey: "chain-coach",
  status: "completed",
  limit: "10",
});
const res = await fetch(`${BASE_URL}/ai/runs?${params}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data, meta } = await res.json();

python

import requests

res = requests.get(
    f"{BASE_URL}/ai/runs",
    headers={"Authorization": f"Bearer {TOKEN}"},
    params={"featureKey": "chain-coach", "status": "completed", "limit": 10},
)
body = res.json()

GET /ai/runs/:runId

Tek bir çalıştırmanın ayrıntılarını alın.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 60/dak

Rica etmek

Create a Run'ın yanıtındaki ("data.id") "id"yi "$RUN_ID" olarak kullanın.

Cevap

Yanıt Örneği

json

{
  "data": {
    "id": "cm5run001",
    "featureKey": "chain-coach",
    "status": "completed",
    "output": null,
    "startedAt": "2026-03-17T10:00:00.000Z",
    "completedAt": "2026-03-17T10:00:12.000Z",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Yanıt Alanları

Field	Type	Description
`id`	string	Run ID
`featureKey`	string	Feature that triggered the run
`status`	string	`queued`, `running`, `completed`, `failed`, `cancelled`
`output`	object \| null	Run output
`startedAt`	string \| null	ISO 8601
`completedAt`	string \| null	ISO 8601 or null
`createdAt`	string	ISO 8601

Kod Örnekleri

JavaScriptPython

javascript

const runId = process.env.RUN_ID; // id of the run to fetch

const res = await fetch(`${BASE_URL}/ai/runs/${runId}`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

python

import os
import requests

run_id = os.environ["RUN_ID"]  # id of the run to fetch

res = requests.get(
    f"{BASE_URL}/ai/runs/{run_id}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

GET /ai/runs/:runId/steps

Bir çalıştırmada yürütülen tüm adımları listeleyin.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 60/dak

Rica etmek

Create a Run'ın yanıtındaki ("data.id") "id"yi "$RUN_ID" olarak kullanın.

Cevap

Yanıt Örneği

json

{
  "data": [
    {
      "id": "cm5step01",
      "runId": "cm5run001",
      "type": "llm_call",
      "status": "completed",
      "input": { "prompt": "Analyze completion history data..." },
      "output": { "response": "Based on your data..." },
      "tokensUsed": 1250,
      "durationMs": 3400,
      "createdAt": "2026-03-17T10:00:01.000Z"
    }
  ]
}

Yanıt Alanları

Field	Type	Description
`id`	string	Step ID
`runId`	string	Parent run ID
`type`	string	Step type (e.g., `llm_call`)
`status`	string	Step status
`input`	object	Step input
`output`	object	Step output
`tokensUsed`	number	Tokens consumed
`durationMs`	number	Execution duration in ms
`createdAt`	string	ISO 8601

Kod Örnekleri

JavaScriptPython

javascript

const runId = process.env.RUN_ID; // id of the run to list steps for

const res = await fetch(`${BASE_URL}/ai/runs/${runId}/steps`, {
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

python

import os
import requests

run_id = os.environ["RUN_ID"]  # id of the run to list steps for

res = requests.get(
    f"{BASE_URL}/ai/runs/{run_id}/steps",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

GET /ai/runs/:runId/stream

Bir çalıştırma yürütülürken gerçek zamanlı güncellemeleri almak için Sunucu Tarafından Gönderilen Olaylar akışına bağlanın.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 20/dak

Rica etmek

Create a Run'ın yanıtındaki ("data.id") "id"yi "$RUN_ID" olarak kullanın.

Cevap

Yanıt Örneği

event: run.started
data: {"eventId":1,"type":"run.started","runId":"cm5run001","timestamp":"...","payload":{}}

event: message.delta
data: {"eventId":2,"type":"message.delta","runId":"cm5run001","timestamp":"...","payload":{"delta":"Based on your completion history data, "}}

event: message.delta
data: {"eventId":3,"type":"message.delta","runId":"cm5run001","timestamp":"...","payload":{"delta":"I recommend starting with smaller "}}

event: message.completed
data: {"eventId":4,"type":"message.completed","runId":"cm5run001","timestamp":"...","payload":{"content":"Based on your completion history data, I recommend starting with smaller goals."}}

event: run.settlement.completed
data: {"eventId":5,"type":"run.settlement.completed","runId":"cm5run001","timestamp":"...","payload":{"status":"completed"}}

Yanıt Alanları

Field	Type	Description
`eventId`	number	Monotonically increasing event counter for this run
`type`	string	SSE event type — see SSE Streaming reference for the full catalog
`runId`	string	Run UUID
`timestamp`	string	ISO 8601 event timestamp
`payload`	object	Event-specific data (e.g. `{ delta }` for `message.delta`)

Kod Örnekleri

JavaScriptPython

javascript

// Browser — uses built-in EventSource (no auth header support)
// For Node.js, install: npm install eventsource
import EventSource from 'eventsource';

const runId = process.env.RUN_ID; // id of the run to stream

const es = new EventSource(
  `${BASE_URL}/ai/runs/${runId}/stream`,
  { headers: { Authorization: `Bearer ${TOKEN}` } }
);

es.addEventListener('message.delta', (e) => {
  const { payload } = JSON.parse(e.data);
  process.stdout.write(payload.delta);
});

es.addEventListener('run.settlement.completed', () => es.close());
es.addEventListener('run.failed', (e) => {
  console.error('Run failed:', JSON.parse(e.data));
  es.close();
});

python

import os
import sseclient
import requests
import json

run_id = os.environ["RUN_ID"]  # id of the run to stream

response = requests.get(
    f"{BASE_URL}/ai/runs/{run_id}/stream",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Accept": "text/event-stream",
    },
    stream=True,
)
client = sseclient.SSEClient(response)
for event in client.events():
    if event.event == "message.delta":
        data = json.loads(event.data)
        print(data["payload"]["delta"], end="", flush=True)
    elif event.event == "run.settlement.completed":
        break

POST /ai/runs/:runId/cancel

Şu anda çalışan bir çalıştırmayı iptal edin.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 30/dak

Rica etmek

Create a Run'ın yanıtındaki ("data.id") "id"yi "$RUN_ID" olarak kullanın.

Cevap

Yanıt Örneği

json

{
  "data": {
    "cancelled": true
  }
}

Yanıt Alanları

Field	Type	Description
`cancelled`	boolean	`true` if the run was cancelled; `false` if you may not cancel the run or it has already finished

Kimler iptal edebilir. Hesap sahipleri (owner) ve yöneticileri (admin) isteğin çalıştığı çalışma alanındaki herhangi bir çalıştırmayı iptal edebilir; diğer üyeler yalnızca kendi başlattıkları çalıştırmaları iptal edebilir. Hesaptan çıkarılmış veya askıya alınmış bir üye, kendi başlattıkları da dahil olmak üzere oradaki hiçbir çalıştırmayı iptal edemez. Mevcut olmayan bir runId ya da başka bir hesapta veya çalışma alanında olup sizin başlatmadığınız bir çalıştırma 403 ile reddedilir. Diğer tüm retler { "cancelled": false } döndürür; bu, zaten tamamlanmış bir çalıştırma için verilen yanıtla aynıdır, bu yüzden yanıt hangi durumun geçerli olduğunu açığa vurmaz. İptal en iyi çabadır; halihazırda aktarılan jetonlar geri çekilmez ve yine de faturalandırılabilir.

Kod Örnekleri

JavaScriptPython

javascript

const runId = process.env.RUN_ID; // id of the run to cancel

const res = await fetch(`${BASE_URL}/ai/runs/${runId}/cancel`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

python

import os
import requests

run_id = os.environ["RUN_ID"]  # id of the run to cancel

res = requests.post(
    f"{BASE_URL}/ai/runs/{run_id}/cancel",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

POST /ai/runs/:runId/retry

Başarısız bir çalıştırmayı yeniden deneyin ve aynı girişten yeni bir çalıştırma oluşturun.

Kimlik Doğrulama: JWT Taşıyıcı jetonu + aktif AI yetkisi gereklidir. Hız sınırı: 10/dak

Rica etmek

Create a Run'ın yanıtındaki ("data.id") "id"yi "$RUN_ID" olarak kullanın.

Cevap

Yanıt Örneği

json

{
  "data": {
    "id": "cm5run002",
    "featureKey": "chain-coach",
    "status": "queued",
    "retriedFromRunId": "cm5run001",
    "createdAt": "2026-03-17T10:05:00.000Z"
  }
}

Yanıt Alanları

Field	Type	Description
`id`	string	New run ID
`featureKey`	string	Feature that triggered the run
`status`	string	`queued`, `running`, `completed`, `failed`, `cancelled`
`retriedFromRunId`	string	Original run ID that was retried
`createdAt`	string	ISO 8601

Kod Örnekleri

JavaScriptPython

javascript

const runId = process.env.RUN_ID; // id of the failed run to retry

const res = await fetch(`${BASE_URL}/ai/runs/${runId}/retry`, {
  method: "POST",
  headers: { Authorization: `Bearer ${TOKEN}` },
});
const { data } = await res.json();

python

import os
import requests

run_id = os.environ["RUN_ID"]  # id of the failed run to retry

res = requests.post(
    f"{BASE_URL}/ai/runs/{run_id}/retry",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
data = res.json()["data"]

Yapay Zeka Koşuları ​

Orkestrasyon Çözüm Yolunu Çalıştır ​

Uç noktalar ​

GET /ai/features ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

POST /ai/runs/:runId/resume ​

POST /ai/features/:featureKey/runs ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

GET /ai/runs ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

GET /ai/runs/:runId ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

GET /ai/runs/:runId/steps ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

GET /ai/runs/:runId/stream ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

POST /ai/runs/:runId/cancel ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

POST /ai/runs/:runId/retry ​

Rica etmek ​

Cevap ​

Yanıt Örneği ​

Yanıt Alanları ​

Kod Örnekleri ​

Yapay Zeka Koşuları

Orkestrasyon Çözüm Yolunu Çalıştır

Uç noktalar

GET /ai/features

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

POST /ai/runs/:runId/resume

POST /ai/features/:featureKey/runs

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

GET /ai/runs

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

GET /ai/runs/:runId

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

GET /ai/runs/:runId/steps

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

GET /ai/runs/:runId/stream

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

POST /ai/runs/:runId/cancel

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri

POST /ai/runs/:runId/retry

Rica etmek

Cevap

Yanıt Örneği

Yanıt Alanları

Kod Örnekleri