مستندات API

با API ایجنت‌هاتون ارتباط بگیرید. پیام ارسال کنید، پاسخ استریم دریافت کنید و ایجنت‌هاتون رو در هر اپلیکیشنی ادغام کنید.

احراز هویت

از بخش تنظیمات ایجنت → کلیدهای API یک کلید بسازید. کلید را در هدر X-API-Key تمام درخواست‌ها ارسال کنید.

X-API-Key: agk_YOUR_API_KEY

ارسال پیام

POST/api/chat/{AGENT_ID}/message

پیام ارسال کنید و پاسخ کامل را یکجا دریافت کنید.

فیلدنوعتوضیح
message*stringمتن پیام
user_idstringشناسه کاربر (برای حافظه مکالمه)
thread_idstringشناسه مکالمه (جداسازی موضوعات)

نمونه درخواست

curl -X POST https://agent.noqte.ai/api/chat/{AGENT_ID}/message \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "سلام", "user_id": "user_1"}'

پاسخ

{
  "response": "سلام! چطور می‌تونم کمکت کنم؟",
  "user_id": "user_1"
}

استریم (SSE)

POST/api/chat/{AGENT_ID}/stream

پاسخ را به‌صورت Server-Sent Events دریافت کنید. مناسب برای نمایش real-time.

رویدادها

token

بخشی از متن پاسخ

tool_call

ایجنت در حال اجرای ابزار

new_message

شروع پیام جدید (بعد از tool)

confirmation

تایید عملیات خطرناک

done

پایان پاسخ

error

خطا

وقتی ایجنت ابزاری اجرا می‌کنه (مثلاً جستجوی وب)، اول tool_call میاد، بعد new_message نشون میده که پاسخ بعدی توی یه پیام جداگانه نمایش داده بشه.

curl -N -X POST https://agent.noqte.ai/api/chat/{AGENT_ID}/stream \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"message": "قیمت دلار چنده؟", "user_id": "user_1"}'

نمونه کد

Python

import requests

response = requests.post(
    "https://agent.noqte.ai/api/chat/{AGENT_ID}/message",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
    },
    json={"message": "سلام", "user_id": "user_1"},
)

print(response.json()["response"])

JavaScript

const res = await fetch("https://agent.noqte.ai/api/chat/{AGENT_ID}/message", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({ message: "سلام", user_id: "user_1" }),
});

const data = await res.json();
console.log(data.response);

JavaScript (استریم)

const res = await fetch("https://agent.noqte.ai/api/chat/{AGENT_ID}/stream", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "YOUR_API_KEY",
  },
  body: JSON.stringify({ message: "سلام", user_id: "user_1" }),
});

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  for (const line of decoder.decode(value).split("\n")) {
    if (!line.startsWith("data: ")) continue;
    const event = JSON.parse(line.slice(6));

    switch (event.type) {
      case "token":
        process.stdout.write(event.content);
        break;
      case "tool_call":
        console.log("\n[Tool] " + event.content);
        break;
      case "new_message":
        console.log("\n--- پیام جدید ---");
        break;
      case "done":
        console.log("\n--- Done ---");
        break;
      case "error":
        console.error("Error: " + event.content);
        break;
    }
  }
}

Python (استریم)

import json, requests

response = requests.post(
    "https://agent.noqte.ai/api/chat/{AGENT_ID}/stream",
    headers={
        "Content-Type": "application/json",
        "X-API-Key": "YOUR_API_KEY",
    },
    json={"message": "سلام", "user_id": "user_1"},
    stream=True,
)

for line in response.iter_lines():
    if not line:
        continue
    line = line.decode()
    if not line.startswith("data: "):
        continue
    event = json.loads(line[6:])
    match event["type"]:
        case "token":
            print(event["content"], end="", flush=True)
        case "tool_call":
            print(f"\n[Tool] {event['content']}")
        case "new_message":
            print("\n--- پیام جدید ---")
        case "done":
            print("\n--- Done ---")
        case "error":
            print(f"Error: {event['content']}")

ایزوله‌سازی مکالمه

هر کاربر مکالمه مستقل دارد. با user_id و thread_id مکالمات رو جدا کنید.

فیلدنوعتوضیح
user_idstringشناسه کاربر — هر کاربر حافظه جدا دارد
thread_idstringشناسه مکالمه — برای جداسازی موضوعات مختلف
user_namestringنام کاربر (برای شخصی‌سازی پاسخ)

نکات مهم

• بدون user_id: هر درخواست session جدید میسازه

• با user_id: مکالمه ادامه‌دار (حافظه حفظ میشه)

• با thread_id: موضوعات مختلف برای یک کاربر

تنظیمات ایجنت (پابلیک)

GET/api/chat/{AGENT_ID}/config

اطلاعات عمومی ایجنت — بدون نیاز به API Key.

پاسخ

{
  "agent_name": "قیمت طلا",
  "description": "ایجنت قیمت لحظه‌ای طلا",
  "theme": {
    "title": "قیمت لحظه‌ای طلا",
    "logo_url": "https://...",
    "welcome_message": "سلام! چطور کمکت کنم؟",
    "primary_color": "#3B82F6"
  }
}

تبدیل صدا به متن (STT)

صدای فارسی رو با دقت بالا به متن تبدیل می‌کنه. هزینه از موجودی توکن حسابت کسر می‌شه.

POST/api/stt/transcribe

احراز هویت

با هدر X-API-Key: agk_... — همون کلیدی که برای چت ایجنتت استفاده می‌کنی.

(یا Authorization: Bearer JWT اگه از داشبورد وب استفاده می‌کنی.)

فرم‌دیتا

فیلدنوعتوضیح
audio*fileفایل صدا — webm / mp3 / wav / m4a / ogg (حداکثر ۲۵MB)
duration*floatمدت صدا به ثانیه (حداکثر ۳۰۰ثانیه)
agent_idstringایجنتی که هزینه روش حساب میشه (پیش‌فرض: builder)

هزینه

۳۰ توکن به ازای هر ثانیه صدا — مثلاً ۱۰ ثانیه = ۳۰۰ توکن. قبل از تبدیل، موجودی چک می‌شه.

نمونه با cURL

curl -X POST https://agent.noqte.ai/api/stt/transcribe \
  -H "X-API-Key: agk_YOUR_KEY" \
  -F "audio=@voice.webm" \
  -F "duration=8.4" \
  -F "agent_id={AGENT_ID}"

پاسخ

{
  "text": "سلام، می‌خوام قیمت طلا رو بدونم",
  "duration_seconds": 8.4,
  "tokens_charged": 252
}

نمونه با Python

import httpx

with open("voice.webm", "rb") as f:
    audio_data = f.read()

# duration رو از روی فایل صدا حساب کن یا از ضبط‌کننده بگیر
duration = 8.4

resp = httpx.post(
    "https://agent.noqte.ai/api/stt/transcribe",
    headers={"X-API-Key": "agk_YOUR_KEY"},
    files={"audio": ("voice.webm", audio_data, "audio/webm")},
    data={"duration": str(duration), "agent_id": "{AGENT_ID}"},
    timeout=60,
)
print(resp.json())

کدهای خطا

401 — کلید نامعتبر

402 — موجودی توکن کافی نیست

413 — فایل بزرگ‌تر از ۲۵MB

422 — صدا قابل شناسایی نبود

503 — سرویس موقتاً غیرفعاله (پشتیبانی اطلاع داره)

کلید کاربران (اختیاری)

اگه ایجنتت به سرویس‌هایی وصله که هر کاربر باید کلید/توکن جدای خودش رو داشته باشه (مثلاً صرافی، ووکامرس، حسابداری)، می‌تونی کلید هر کاربر رو یه بار ذخیره کنی و بعد توی چت‌ها فقط با user_id بفرستی — ایجنت خودکار کلید درست رو استفاده می‌کنه.

⚙️ این بخش اختیاریه. اگه ایجنتت فقط از سرویس‌های مشترک (که کلیدش مال خودته) یا بدون نیاز به احراز هویت کار می‌کنه، این endpointها رو نادیده بگیر.

احراز هویت

با X-API-Key: agk_... (همون کلید ایجنت)

۱. ذخیره کلید کاربر

PUT/api/users/{user_id}/credentials/{service_id}
curl -X PUT https://agent.noqte.ai/api/users/bob_42/credentials/abantether \
  -H "X-API-Key: agk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": "user_aban_api_key_xxx",
    "type": "api_key"
  }'

user_id: شناسه کاربری که خودت میدی (هر چیزی، مثلاً bob_42 یا email یا UUID)
service_id: همون شناسه‌ی سرویسی که توی ایجنت تنظیم کردی (مثل abantether, woocommerce, hesabfa)
credential: کلید/توکن کاربر (encrypted ذخیره می‌شه)

۲. چت معمولی — کلید خودکار وصل می‌شه

curl -X POST https://agent.noqte.ai/api/chat/{AGENT_ID}/message \
  -H "X-API-Key: agk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"bob_42","message":"موجودی تترم چقدره؟"}'

ایجنت موقع فراخوانی tool که نیاز به کلید کاربر داره، خودکار کلید bob_42 رو از DB می‌خونه و وصلش می‌کنه به request.

۳. مدیریت کلیدها

فیلدنوعتوضیح
GET /api/users/{user_id}/credentialslistلیست سرویس‌هایی که کلید ست شده — مقدار کلید برنمی‌گرده
GET /api/users/{user_id}/credentials/{service_id}checkوضعیت یک سرویس خاص (set / not set + متادیتا)
DELETE /api/users/{user_id}/credentials/{service_id}removeحذف یک کلید
DELETE /api/users/{user_id}/credentialslogoutحذف همه کلیدهای کاربر (logout)

امنیت + scope

• کلیدها با AES-256 رمزنگاری می‌شن قبل از ذخیره

• هیچ endpoint کلید رو واقعی برنمی‌گردونه — فقط set: true/false

• scope: کلید مال (ایجنت، user_id، service) هست. ایجنت دیگه‌ای دسترسی نداره

• اگه کلید ست نشده باشه و ایجنت بخواد ازش استفاده کنه، یه پیام خطا برمی‌گرده با needs_credential: true

نمونه Python

import httpx

API = "https://agent.noqte.ai"
KEY = "agk_YOUR_KEY"
H = {"X-API-Key": KEY}

# 1. وقتی کاربر کلیدش رو وارد می‌کنه (یه بار)
r = httpx.put(
    f"{API}/api/users/bob_42/credentials/abantether",
    headers=H,
    json={"credential": user_provided_key},
)
assert r.json()["ok"]

# 2. چت‌های بعدی — فقط user_id بفرست
r = httpx.post(
    f"{API}/api/chat/{AGENT_ID}/message",
    headers=H,
    json={"user_id": "bob_42", "message": "خرید ۱۰ تتر"},
)
print(r.json()["response"])

# 3. وقتی کاربر logout می‌کنه
httpx.delete(f"{API}/api/users/bob_42/credentials", headers=H)

محدودیت‌ها

• هر درخواست از موجودی توکن حساب شما کسر می‌شود.

• سقف مصرف روزانه هر ایجنت از تنظیمات → کیف پول قابل تنظیم است (پیش‌فرض ۵,۰۰۰ توکن).

• بدون API Key هم کار میکنه (پابلیک) ولی مصرف از حساب مالک کسر میشه.

• در صورت اتمام موجودی، پاسخ 402 دریافت خواهید کرد.