تجاوز إلى المحتوى الرئيسي
قارن لي

API Documentation

Complete reference for Qaranly public API and Agent API.

Authentication

Public API (v1)

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Agent API

Include your agent API key in the x-agent-api-key header:

x-agent-api-key: qrn_your_api_key_here

API Key Scopes

  • agent:read - Read access to all content
  • agent:write - Create and update content
  • agent:delete - Delete content
  • admin - Full access including users and config

Recommended: create one dedicated Openclaw key per automation job, keep it server-side only, and grant the smallest scope set possible. Add an IP allowlist and expiry date when you can.

Public API (v1)

Base URL: https://qaranly.com/api/v1

Rate limit: 60 req/min, 10,000 req/day.

GET/api/v1/toolsscope: read

List tools with filtering and pagination.

Query params: category, search, featured, limit, offset, locale

GET/api/v1/tools/[slug]scope: read

Get a single tool by its slug.

Query params: locale

GET/api/v1/categoriesscope: read

List all tool categories.

Query params: locale

Agent API

Full content management API for automated agents. Base URL: https://qaranly.com/api/agent

المدونة

GET/api/agent/blogscope: agent:read

List blog posts with pagination.

Query params: page, limit, published

POST/api/agent/blogscope: agent:write

Create or upsert a blog post.

{
  "slug": "my-post",
  "published": true,
  "authorId": "uuid",
  "translations": {
    "ar": {
      "title": "عنوان المقال",
      "excerpt": "ملخص قصير",
      "content": "محتوى المقال الكامل",
      "metaTitle": "عنوان SEO",
      "metaDescription": "وصف SEO"
    }
  }
}
PUT/api/agent/blogscope: agent:write

Update an existing blog post by slug.

{ "slug": "my-post", "translations": { "ar": { "title": "..." } } }
DELETE/api/agent/blog?slug=my-postscope: agent:delete

Delete a blog post by slug.

الأخبار

GET/api/agent/newsscope: agent:read

List news articles.

Query params: page, limit

POST/api/agent/newsscope: agent:write

Create or upsert a news article.

{
  "slug": "news-slug",
  "source": "Source Name",
  "sourceUrl": "https://...",
  "imageUrl": "https://...",
  "titleAr": "عنوان الخبر",
  "excerptAr": "ملخص",
  "contentAr": "المحتوى",
  "publishedAt": "2024-01-01T00:00:00Z"
}
PUT/api/agent/newsscope: agent:write

Update a news article by slug.

DELETE/api/agent/news?slug=news-slugscope: agent:delete

Delete a news article.

الأدوات

GET/api/agent/toolsscope: agent:read

List all tools (admin view).

Query params: page, limit

POST/api/agent/toolsscope: agent:write

Create or upsert a tool.

{
  "slug": "tool-slug",
  "websiteUrl": "https://...",
  "pricingType": "free|freemium|paid",
  "translations": {
    "ar": {
      "name": "اسم الأداة",
      "shortDescription": "وصف قصير",
      "fullContent": "وصف كامل"
    }
  },
  "categoryIds": ["uuid1", "uuid2"],
  "imageUrl": "https://...",
  "isVerified": false
}
PUT/api/agent/toolsscope: agent:write

Update a tool by slug.

DELETE/api/agent/tools?slug=tool-slugscope: agent:delete

Soft-delete a tool.

الفئات

GET/api/agent/categoriesscope: agent:read

List all categories.

POST/api/agent/categoriesscope: agent:write

Create a new category.

{ "slug": "cat-slug", "iconName": "Brain", "translations": { "ar": "اسم التصنيف" } }
PUT/api/agent/categoriesscope: agent:write

Update a category.

DELETE/api/agent/categories?slug=cat-slugscope: agent:delete

Delete a category.

الأدلة

GET/api/agent/guidesscope: agent:read

List published guides.

POST/api/agent/guidesscope: agent:write

Create a guide.

{
  "slug": "guide-slug",
  "guideType": "getting-started",
  "featured": false,
  "readingTimeMinutes": 10,
  "published": true,
  "translations": {
    "ar": {
      "title": "...", "description": "...",
      "content": "...", "excerpt": "..."
    }
  }
}
PUT/api/agent/guidesscope: agent:write

Update a guide.

DELETE/api/agent/guides?slug=guide-slugscope: agent:delete

Delete a guide.

المصطلحات

GET/api/agent/glossaryscope: agent:read

List glossary terms.

POST/api/agent/glossaryscope: agent:write

Create a glossary term.

{ "slug": "term-slug", "translations": { "ar": { "term": "المصطلح", "definition": "التعريف", "examples": ["مثال 1"] } } }
DELETE/api/agent/glossary?slug=term-slugscope: agent:delete

Delete a glossary term.

الإحصاءات والإعدادات

GET/api/agent/statsscope: agent:read

Get site statistics (tool count, user count, blog count, news count).

GET/api/agent/usersscope: admin

List registered users (admin only).

Query params: page, limit

GET/api/agent/configscope: agent:read

Get site configuration and content counts.

مسار Openclaw

Use the /api/agent/* endpoints directly from Openclaw to create or update tools, blog posts, news items, prompts, and categories without a separate manual publishing queue.

المسار الموصى به

  1. 1. تحقّق من المصدر وطبّع البيانات قبل الإرسال.
  2. 2. استدعِ نقطة النهاية المناسبة باستخدام x-agent-api-key.
  3. 3. اترك واجهة البرمجة تعيد التحقق من ذاكرة المحتوى تلقائيًا.
  4. 4. سجّل العملية داخل تتبع وكيلك لأغراض المراجعة.
import { createOpenclawClient } from '@/lib/openclaw';

const client = createOpenclawClient({
  apiKey: process.env.OPENCLAW_AGENT_API_KEY!,
});

await client.upsertTool({
  slug: 'new-tool',
  websiteUrl: 'https://example.com',
  pricingType: 'freemium',
  translations: {
    ar: {
      name: 'اسم الأداة',
      shortDescription: 'وصف قصير',
      fullContent: 'وصف كامل'
    }
  },
  categoryIds: ['category-id'],
});

The helper in lib/openclaw.ts keeps the contract in one place so the agent can publish blog posts, news, prompts, and tools consistently.

Getting Started

1. Sign in to your account and visit the Dashboard.

2. Open API Keys from an admin account and create a dedicated key for Openclaw. Do not reuse a global admin key.

3. Give it only the scopes it needs, ideally agent:read and agent:write.

4. Add agent:delete only if the bot truly needs deletion support.

5. Use an IP allowlist and expiry date if your deployment setup allows it.

6. Use the API key in the x-agent-api-key header for all Agent API requests.

7. The API key is shown only once on creation. Store it securely.

8. For a reusable client, import createOpenclawClient from lib/openclaw.ts.

Error Responses

401 - Missing or invalid API key

403 - Insufficient scope for this operation

400 - Invalid request body (validation error)

404 - Resource not found

500 - Internal server error