Pulshub API Documentation
RESTful API for accessing Persian news articles.
Authentication
All API endpoints require an API key. Pass it in one of these ways:
# Header (recommended)
X-API-Key: sk_pls_your_key_here
# Bearer token
Authorization: Bearer sk_pls_your_key_here
# Query param
GET /api/v1/articles?api_key=sk_pls_your_key_here
To get an API key, contact the admin or visit /admin/users.
Rate Limiting
Requests are limited per API key per hour. On limit exceeded, the server returns 429 Too Many Requests.
Default limit: 1000 requests/hour (configurable per key)
Base URL
https://pulsehub.ir/api/v1
Endpoints
GET
/api/v1/articles
— List articles
Query Parameters
| Param | Type | Description |
|---|---|---|
| lang | string | fa or en — filter by language |
| category_id | int | Filter by category ID |
| page | int | Page number (default: 1) |
curl -H "X-API-Key: sk_pls_..." \
"https://pulsehub.ir/api/v1/articles?lang=fa&page=1"
{
"data": [
{
"id": 123,
"title": "عنوان مقاله",
"summary": "خلاصه مقاله...",
"url": "https://source.com/article",
"image_url": "https://...",
"author": "نویسنده",
"language": "fa",
"category_id": 5,
"published_at": "2026-06-30T05:00:00Z"
}
],
"page": 1,
"has_next": true
}
GET
/api/v1/articles/:id
— Single article
curl -H "X-API-Key: sk_pls_..." \
"https://pulsehub.ir/api/v1/articles/123"
{
"data": {
"id": 123,
"title": "عنوان مقاله",
"body": "متن کامل مقاله...",
"summary": "خلاصه...",
"url": "https://...",
"author": "نویسنده",
"language": "fa",
"published_at": "2026-06-30T05:00:00Z"
}
}
GET
/api/v1/categories
— List categories
curl -H "X-API-Key: sk_pls_..." \
"https://pulsehub.ir/api/v1/categories"
{
"data": [
{ "id": 1, "name_fa": "اقتصادی", "name_en": "Economy", "slug": "economy" },
{ "id": 2, "name_fa": "سیاسی", "name_en": "Politics", "slug": "politics" }
]
}
GET
/api/v1/search
— Search articles
| Param | Required | Description |
|---|---|---|
| q | yes | Search query |
| lang | no | Filter by language |
curl -H "X-API-Key: sk_pls_..." \
"https://pulsehub.ir/api/v1/search?q=بورس&lang=fa"
Error Codes
| Code | Meaning |
|---|---|
| 400 | Bad request — missing or invalid parameter |
| 401 | Unauthorized — missing or invalid API key |
| 404 | Not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |