Genel API hızlı başlangıç

Bu rehberde: OrqLabs'ı kendi yazılımınızdan kullanırsınız: aday oluşturma, iş akışı çalıştırıp sonucu bekleme, rapor okuma, ajan çalıştırma. curl, Node.js ve Python örnekleri var. Bu rehber yazılımcılar içindir.

⏱ 20 dakika

API ne işe yarar?#

Panelde yaptığınız her şey aynı API üzerinden çalışır. Kendi sisteminizden de aynı işleri yapabilirsiniz. Örneğin: sitenizdeki üyelik formundan aday oluşturmak veya kendi uygulamanızdan bir iş akışını tetiklemek.

Temeller#

Geliştirici notu: Yerel kurulumda taban adres http://localhost:4000/api/v1; demo hesap demo@agentflow.local / Demo123!.

Organizasyon kimliğiniz Ayarlar → API anahtarları sayfasında görünür.

Kimlik doğrulama#

API anahtarı (önerilen)#

export API_URL=https://api.orqlabs.com
export ORG=org_01J...
export KEY=af_live_...
curl -s -H "X-Api-Key: $KEY" "$API_URL/api/v1/orgs/$ORG"

Anahtar oluşturma: API anahtarları.

Kullanıcı oturumu (JWT)#

TOKENS=$(curl -s -X POST "$API_URL/api/v1/auth/login" -H "Content-Type: application/json" \
  -d '{"email":"siz@sirket.com","password":"…"}')
ACCESS=$(echo "$TOKENS" | jq -r .tokens.accessToken)
REFRESH=$(echo "$TOKENS" | jq -r .tokens.refreshToken)
curl -s -H "Authorization: Bearer $ACCESS" "$API_URL/api/v1/orgs"
# 15 dk sonra:
curl -s -X POST "$API_URL/api/v1/auth/refresh" -H "Content-Type: application/json" -d "{\"refreshToken\":\"$REFRESH\"}"

1. Aday oluşturma#

POST /orgs/:orgId/leads (e-posta/telefon/web sitesiyle tekilleştirir):

curl -s -X POST "$API_URL/api/v1/orgs/$ORG/leads" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_01J...",
    "name": "Ayşe Kaya",
    "email": "ayse@ornek.com",
    "phone": "+905551112233",
    "company": "Örnek Ltd",
    "website": "https://ornek.com",
    "source": "website",
    "tags": ["inbound", "webinar"],
    "custom": { "consentMarketing": true }
  }'

Yeni ise 201, eşleşip güncellendiyse 200 döner.

Listeleme: GET /orgs/:orgId/leads?status=QUALIFIED&minScore=70&tags=webinar&page=1&pageSize=50&sort=-score. Ayrıntı: GET /orgs/:orgId/leads/:id. Toplu: POST /leads/bulk { ids, action: "tag", value: "vip" }. İstatistik: GET /leads/stats.

2. İş akışı çalıştırma ve sonucu bekleme#

RUN=$(curl -s -X POST "$API_URL/api/v1/orgs/$ORG/workflows/$WF/run" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"input":{"topic":"Kış kampanyası","platforms":["LINKEDIN"]},"testMode":false}')
RUN_ID=$(echo "$RUN" | jq -r .id)     # status: QUEUED

until STATUS=$(curl -s -H "X-Api-Key: $KEY" "$API_URL/api/v1/orgs/$ORG/runs/$RUN_ID" | jq -r .status); \
      [ "$STATUS" != "QUEUED" ] && [ "$STATUS" != "RUNNING" ]; do sleep 3; done
echo "$STATUS"   # SUCCEEDED | FAILED | WAITING | CANCELED

• input tetikleyici öğesinin verisi olur.
• testMode: true yayın/mesaj kutularını kuru çalıştırır.
• WAITING → onay bekliyor; GET /orgs/:orgId/approvals?status=PENDING ve POST /approvals/:id/approve.
• Canlı takip: SSE olayları.
• Şablondan iş akışı: POST /orgs/:orgId/templates/daily-social-content/use { name, projectId }.

3. Raporlar#

curl -s -H "X-Api-Key: $KEY" \
  "$API_URL/api/v1/orgs/$ORG/reports?type=LEAD_LIST&projectId=$PRJ&page=1&pageSize=10&sort=-createdAt"
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  "$API_URL/api/v1/orgs/$ORG/reports/$REPORT_ID/apply-recommendation" -d '{"index":0}'

Rapor türleri: CONTENT_PLAN, SOCIAL_PERFORMANCE, LEAD_LIST, LEAD_QUALIFICATION, OUTREACH_SUMMARY, MARKET_RESEARCH, COMPETITOR_ANALYSIS, SEO_AUDIT, TRAFFIC_STRATEGY, ANALYTICS_REVIEW, CAMPAIGN_PLAN, CAMPAIGN_SUMMARY, CHATBOT_INSIGHTS, WEEKLY_DIGEST, GENERAL.

4. Tek ajan çalıştırma#

AR=$(curl -s -X POST "$API_URL/api/v1/orgs/$ORG/agents/run" \
  -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{
    "type": "MARKET_ANALYST",
    "task": "Türkiye online specialty kahve pazarını değerlendir; 3 fırsat çıkar, kaynak ver.",
    "input": { "focus": "Türkiye online specialty kahve", "region": "Türkiye", "depth": "quick" },
    "projectId": "prj_01J...",
    "modelId": "claude-sonnet-5"
  }')
AR_ID=$(echo "$AR" | jq -r .id)
curl -s -H "X-Api-Key: $KEY" "$API_URL/api/v1/orgs/$ORG/agent-runs/$AR_ID" | jq '{status, summary, usage}'

Kayıtlı ajan: POST /orgs/:orgId/agents/:id/run { task, input?, projectId? }. İptal: POST /agent-runs/:id/cancel.

5. İçerik#

# Taslak oluştur
curl -s -X POST "$API_URL/api/v1/orgs/$ORG/content" -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"prj_01J...","platform":"LINKEDIN","body":"Yeni kavurma…","hashtags":["#kahve"],"scheduledAt":"2026-10-01T08:45:00+03:00","integrationId":"int_01J..."}'
# Onayla
curl -s -X POST "$API_URL/api/v1/orgs/$ORG/content/$POST_ID/approve" -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"body":"Yeni kavurma: Etiyopya Guji…"}'
# Ajanla üret
curl -s -X POST "$API_URL/api/v1/orgs/$ORG/content/generate" -H "X-Api-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"projectId":"prj_01J...","platforms":["X","LINKEDIN"],"topic":"Sonbahar kavurmaları","count":2,"language":"tr"}'

Takvim: GET /content/calendar?from=&to=&projectId=. Medya: POST /orgs/:orgId/media/upload (multipart) → { url }.

6. Kullanım ve maliyet#

curl -s -H "X-Api-Key: $KEY" "$API_URL/api/v1/orgs/$ORG/usage?from=2026-09-01&to=2026-09-30&groupBy=model"
curl -s -X POST -H "X-Api-Key: $KEY" -H "Content-Type: application/json" "$API_URL/api/v1/orgs/$ORG/stats/query" \
  -d '{"metrics":["leads.created","leads.qualified"],"from":"2026-09-01","to":"2026-09-30","granularity":"week"}'

Node.js örneği#

const API = "https://api.orqlabs.com/api/v1";
const ORG = "org_01J...";
const headers = { "X-Api-Key": process.env.ORQLABS_API_KEY, "Content-Type": "application/json" };

async function api(path, init = {}) {
  const res = await fetch(`${API}${path}`, { ...init, headers: { ...headers, ...(init.headers ?? {}) } });
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    throw new Error(`${res.status} ${body.code ?? body.error}: ${JSON.stringify(body.message)}`);
  }
  return res.status === 204 ? null : res.json();
}

const lead = await api(`/orgs/${ORG}/leads`, { method: "POST", body: JSON.stringify({ name: "Ayşe Kaya", email: "ayse@ornek.com", projectId: "prj_01J..." }) });
let run = await api(`/orgs/${ORG}/workflows/wf_01J.../run`, { method: "POST", body: JSON.stringify({ input: { leadId: lead.id } }) });
while (["QUEUED", "RUNNING"].includes(run.status)) {
  await new Promise((r) => setTimeout(r, 3000));
  run = await api(`/orgs/${ORG}/runs/${run.id}`);
}
console.log(run.status, run.costUsd);

Python örneği#

import os, time, requests

API = "https://api.orqlabs.com/api/v1"
ORG = "org_01J..."
H = {"X-Api-Key": os.environ["ORQLABS_API_KEY"], "Content-Type": "application/json"}

def api(method, path, **kw):
    r = requests.request(method, f"{API}{path}", headers=H, timeout=30, **kw)
    if r.status_code == 429:
        time.sleep(int(r.headers.get("Retry-After", "5")))
        return api(method, path, **kw)
    r.raise_for_status()
    return r.json() if r.content else None

leads = api("GET", f"/orgs/{ORG}/leads", params={"status": "QUALIFIED", "minScore": 70, "pageSize": 100})
for lead in leads["items"]:
    print(lead["name"], lead["company"], lead["score"])

ar = api("POST", f"/orgs/{ORG}/agents/run", json={
    "type": "REPORT_WRITER", "task": "Geçen haftanın özetini yaz",
    "input": {"period": "last_7_days", "audience": "owner"}, "projectId": "prj_01J..."})
while ar["status"] in ("QUEUED", "RUNNING"):
    time.sleep(5); ar = api("GET", f"/orgs/{ORG}/agent-runs/{ar['id']}")
print(ar["summary"])

Hata kodları#

Sık sorulan sorular#

Kod yazmadan API kullanabilir miyim? Zapier/Make gibi araçlar API'yi kodsuz çağırabilir. Daha basit yol: webhook tetikleyicisi.

Test için gerçek yayın yapılır mı? testMode: true gönderirseniz yayın ve mesaj kutuları kuru çalışır.

Sonraki adım#

• API anahtarları
• Giden webhook'lar
• SSE olayları
• Sık karşılaşılan hatalar