API Endpoints
Complete reference for all available API endpoints.
Base URL
http://localhost:8000/api/v1
GET
/posts/by-user/{platform}/{username}
Retrieve posts from a specific user on a social media platform.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
platform |
string | Required | Social platform: tiktok, instagram, twitter, x, snapchat, or linkedin |
username |
string | Required | The username to fetch posts from (without @) |
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
limit |
integer | 50 | Number of posts to return (max: 100) |
from_date |
date | - | Filter posts published on or after this date (YYYY-MM-DD) |
to_date |
date | - | Filter posts published on or before this date (YYYY-MM-DD) |
media_type |
string | - | Filter by media type: image, video, carousel, reel |
min_likes |
integer | - | Filter posts with at least this many likes |
min_comments |
integer | - | Filter posts with at least this many comments |
sort_by |
string | published_at | Sort field: published_at, likes_count, comments_count, views_count |
sort_order |
string | desc | Sort direction: asc or desc |
Example Request
curl -X GET "http://localhost:8000/api/v1/posts/by-user/tiktok/charlidamelio?limit=20&min_likes=100000" \
-H "Authorization: Bearer YOUR_API_TOKEN"
GET
/posts/by-hashtag/{platform}/{hashtag}
Retrieve posts tagged with a specific hashtag on a social media platform.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
platform |
string | Required | Social platform: tiktok, instagram, twitter, x, snapchat, or linkedin |
hashtag |
string | Required | The hashtag to search for (without #) |
Query Parameters
Same as /posts/by-user endpoint above.
Example Request
curl -X GET "http://localhost:8000/api/v1/posts/by-hashtag/instagram/travel?limit=30" \
-H "Authorization: Bearer YOUR_API_TOKEN"
GET
/posts/search
Advanced search across all platforms with multiple filter options.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
platform |
string | Filter by platform |
username |
string | Filter by author username |
hashtag |
string | Filter by hashtag |
keyword |
string | Search in post content |
from_date |
date | Filter posts from this date (YYYY-MM-DD) |
to_date |
date | Filter posts until this date (YYYY-MM-DD) |
media_type |
string | Filter by media type |
min_likes |
integer | Minimum likes filter |
min_comments |
integer | Minimum comments filter |
limit |
integer | Number of results (default: 50, max: 100) |
Example Request
curl -X GET "http://localhost:8000/api/v1/posts/search?platform=tiktok&keyword=dance&min_likes=50000&limit=25" \
-H "Authorization: Bearer YOUR_API_TOKEN"
GET
/account
Get your account information and current credit balance. This endpoint does not consume any credits.
Example Request
curl -X GET "http://localhost:8000/api/v1/account" \
-H "Authorization: Bearer YOUR_API_TOKEN"
Example Response
{
"success": true,
"data": {
"account": {
"name": "John Doe",
"email": "john@example.com",
"company": "Acme Corp",
"status": "active"
},
"balance": {
"current": 850,
"total_used": 1150
},
"usage": {
"api_calls_30_days": 47
}
}
}
GET
/health
Check API availability. This endpoint does not require authentication.
Example Response
{
"status": "healthy",
"version": "v1",
"timestamp": "2024-01-15T14:30:00Z"
}