قارن لي

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

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

Blog Posts

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.

News Articles

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.

Tools

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.

Categories

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.

Guides

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.

Glossary

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.

Statistics & Config

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.

Getting Started

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

2. Create an API key with the required scopes (agent:read, agent:write, agent:delete).

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

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

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