API Documentation - Social Scraper

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

Authorization: Bearer {your-api-token}

Getting Your API Token

1 Go to Profile → API Tokens
2 Click "Generate New Token"
3 Use the generated token in your requests

GET

/api/tasks

Retrieve paginated list of user's tasks

Query Parameters

Parameter	Type	Description	Default
`status`	string	Filter by status (pending, assigned, processing, completed, failed)	all
`sort_by`	string	Sort field (created_at, status, priority)	created_at
`sort_order`	string	Sort direction (asc, desc)	desc
`per_page`	integer	Items per page	15

Response Example

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "group_id": "123456789",
      "group_name": "Test Group",
      "max_posts": 100,
      "priority": 0,
      "status": "completed",
      "created_at": "2024-01-01T10:00:00Z",
      "has_result": true,
      "posts_count": 85
    }
  ],
  "meta": {
    "total": 50,
    "per_page": 15,
    "current_page": 1,
    "last_page": 4
  },
  "links": {
    "first": "http://example.com/api/tasks?page=1",
    "last": "http://example.com/api/tasks?page=4",
    "prev": null,
    "next": "http://example.com/api/tasks?page=2"
  }
}

POST

/api/tasks

Create a new scraping task

Request Body

Field	Type	Required	Description	Validation
`group_id`	string	Yes	Social media platform ID	required
`group_name`	string	No	Social media platform name	nullable
`max_posts`	integer	Yes	Maximum posts to scrape	min:1, max:500
`priority`	integer	No	Task priority (higher = more priority)	nullable

Request Example

{
  "group_id": "123456789",
  "group_name": "Laravel Developers Vietnam",
  "max_posts": 100,
  "priority": 5
}

Response Example

{
  "status": "success",
  "message": "Task created successfully",
  "data": {
    "id": 1,
    "group_id": "123456789",
    "group_name": "Laravel Developers Vietnam",
    "max_posts": 100,
    "priority": 5,
    "status": "pending",
    "created_at": "2024-01-01T10:00:00Z"
  }
}

GET

/api/tasks/{id}

Get details of a specific task

Response Example

{
  "status": "success",
  "data": {
    "id": 1,
    "group_id": "123456789",
    "group_name": "Laravel Developers Vietnam",
    "max_posts": 100,
    "priority": 5,
    "status": "completed",
    "created_at": "2024-01-01T10:00:00Z",
    "completed_at": "2024-01-01T10:15:00Z",
    "result": {
      "posts_count": 85,
      "duration_seconds": 120
    }
  }
}

PUT

/api/tasks/{id}

Update a pending task (only pending tasks can be updated)

Only tasks with "pending" status can be updated

Request Body

Field	Type	Required	Description	Validation
`group_name`	string	No	Social media platform name	nullable
`max_posts`	integer	No	Maximum posts to scrape	min:1, max:500
`priority`	integer	No	Task priority	nullable

Request Example

{
  "group_name": "Updated Group Name",
  "max_posts": 150,
  "priority": 10
}

DELETE

/api/tasks/{id}

Delete a task

This action cannot be undone

Response Example

{
  "message": "Task deleted successfully"
}

POST

/api/tasks/{id}/reset

Reset a completed or failed task back to pending status

Response Example

{
  "message": "Task reset successfully",
  "task": {
    "id": 1,
    "status": "pending",
    "worker_id": null,
    "completed_at": null
  }
}

GET

/api/tasks/{id}/result

Get detailed result of a completed task

Response Example

{
  "task": {
    "id": 1,
    "group_id": "123456789",
    "status": "completed"
  },
  "result": {
    "posts_count": 85,
    "duration_seconds": 120
  },
  "posts": [
    {
      "id": "post_123",
      "message": "Sample post content",
      "author": "John Doe",
      "created_time": "2024-01-01T09:00:00Z",
      "likes": 25,
      "comments": 5,
      "shares": 2
    }
  ]
}

Error Responses

Common error responses you might encounter

401 Unauthorized

{"message": "Unauthenticated"}

403 Forbidden

{"status": "error", "message": "Unauthorized"}

404 Not Found

{"message": "No result available for this task"}

422 Validation Error

{"status": "error", "message": "Validation failed", "errors": {...}}