API Reference
SocialApparatus provides a comprehensive REST API for integrating with external applications, building mobile apps, or automating community management.
Authentication
The API uses Laravel Sanctum for token-based authentication.
Getting an API Token
POST /api/auth/token
{
"email": "user@example.com",
"password": "your-password",
"device_name": "My App"
}
Response:
{
"token": "1|abc123...",
"user": {
"id": 1,
"name": "John Doe",
"email": "user@example.com"
}
}Using the Token
Include the token in the Authorization header for all authenticated requests:
Authorization: Bearer 1|abc123...
Accept: application/json
Content-Type: application/jsonRevoking Tokens
POST /api/auth/logout
Authorization: Bearer {token}
Response:
{
"message": "Token revoked successfully"
}Rate Limiting
API requests are rate-limited to prevent abuse:
| Endpoint Type | Limit | Window |
|---|---|---|
| General API | 60 requests | Per minute |
| Authentication | 5 requests | Per minute |
| Upload | 10 requests | Per minute |
Rate limit headers are included in every response:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1699999999Users
Get Current User
GET /api/user
Response:
{
"id": 1,
"name": "John Doe",
"username": "johndoe",
"email": "john@example.com",
"avatar_url": "https://...",
"bio": "Software developer",
"location": "New York",
"website": "https://johndoe.com",
"created_at": "2024-01-15T10:30:00Z",
"stats": {
"posts_count": 42,
"followers_count": 128,
"following_count": 85
}
}Get User by ID
GET /api/users/{id}
Response:
{
"id": 2,
"name": "Jane Smith",
"username": "janesmith",
"avatar_url": "https://...",
"bio": "Designer & creator",
"created_at": "2024-02-20T14:00:00Z",
"stats": {
"posts_count": 67,
"followers_count": 256,
"following_count": 142
}
}Update Current User
PATCH /api/user
{
"name": "John Updated",
"bio": "Updated bio",
"location": "Los Angeles",
"website": "https://newsite.com"
}
Response:
{
"id": 1,
"name": "John Updated",
"bio": "Updated bio",
...
}List Users (Paginated)
GET /api/users?page=1&per_page=20
Response:
{
"data": [...],
"meta": {
"current_page": 1,
"last_page": 10,
"per_page": 20,
"total": 195
},
"links": {
"first": "/api/users?page=1",
"last": "/api/users?page=10",
"next": "/api/users?page=2",
"prev": null
}
}Posts
List Posts
GET /api/posts?page=1&per_page=20
Query Parameters:
- category_id: Filter by category
- user_id: Filter by author
- tag: Filter by tag
- sort: latest, popular, trending
- search: Search term
Response:
{
"data": [
{
"id": 1,
"title": "Getting Started with SocialApparatus",
"slug": "getting-started-with-socialapparatus",
"excerpt": "A quick introduction...",
"content": "Full post content...",
"author": {
"id": 1,
"name": "John Doe",
"username": "johndoe"
},
"category": {
"id": 1,
"name": "Tutorials",
"slug": "tutorials"
},
"tags": ["getting-started", "tutorial"],
"stats": {
"views": 1234,
"likes": 56,
"comments": 12
},
"created_at": "2024-03-15T09:00:00Z",
"updated_at": "2024-03-15T09:00:00Z"
}
],
"meta": {...},
"links": {...}
}Get Single Post
GET /api/posts/{id}
Response:
{
"id": 1,
"title": "Getting Started with SocialApparatus",
"content": "Full post content with HTML...",
"author": {...},
"category": {...},
"tags": [...],
"stats": {...},
"comments_count": 12,
"is_liked": true,
"is_bookmarked": false,
"created_at": "2024-03-15T09:00:00Z"
}Create Post
POST /api/posts
{
"title": "My New Post",
"content": "Post content here...",
"category_id": 1,
"tags": ["tag1", "tag2"]
}
Response:
{
"id": 42,
"title": "My New Post",
"slug": "my-new-post",
...
}Update Post
PATCH /api/posts/{id}
{
"title": "Updated Title",
"content": "Updated content..."
}
Response:
{
"id": 42,
"title": "Updated Title",
...
}Delete Post
DELETE /api/posts/{id}
Response:
{
"message": "Post deleted successfully"
}Comments
List Comments for Post
GET /api/posts/{post_id}/comments
Response:
{
"data": [
{
"id": 1,
"content": "Great post!",
"author": {
"id": 2,
"name": "Jane Smith",
"avatar_url": "..."
},
"likes_count": 5,
"is_liked": false,
"replies_count": 2,
"created_at": "2024-03-15T10:00:00Z"
}
],
"meta": {...}
}Create Comment
POST /api/posts/{post_id}/comments
{
"content": "This is my comment",
"parent_id": null // Optional: for replies
}
Response:
{
"id": 15,
"content": "This is my comment",
"author": {...},
"created_at": "2024-03-15T11:00:00Z"
}Update Comment
PATCH /api/comments/{id}
{
"content": "Updated comment text"
}
Response:
{
"id": 15,
"content": "Updated comment text",
...
}Delete Comment
DELETE /api/comments/{id}
Response:
{
"message": "Comment deleted successfully"
}Reactions
Like a Post
POST /api/posts/{id}/like
Response:
{
"liked": true,
"likes_count": 57
}Unlike a Post
DELETE /api/posts/{id}/like
Response:
{
"liked": false,
"likes_count": 56
}React to Content
POST /api/posts/{id}/reactions
{
"type": "love" // like, love, laugh, wow, sad, angry
}
Response:
{
"reaction": "love",
"reactions_summary": {
"like": 45,
"love": 12,
"laugh": 8
}
}Following
Follow User
POST /api/users/{id}/follow
Response:
{
"following": true,
"followers_count": 129
}Unfollow User
DELETE /api/users/{id}/follow
Response:
{
"following": false,
"followers_count": 128
}Get Followers
GET /api/users/{id}/followers
Response:
{
"data": [
{
"id": 3,
"name": "Bob Wilson",
"username": "bobwilson",
"avatar_url": "..."
}
],
"meta": {...}
}Get Following
GET /api/users/{id}/following
Response:
{
"data": [...],
"meta": {...}
}Groups
List Groups
GET /api/groups
Query Parameters:
- type: public, private
- membership: joined, created
- search: Search term
Response:
{
"data": [
{
"id": 1,
"name": "Laravel Developers",
"slug": "laravel-developers",
"description": "A community for Laravel enthusiasts",
"type": "public",
"members_count": 456,
"is_member": true,
"cover_image": "https://...",
"created_at": "2024-01-01T00:00:00Z"
}
],
"meta": {...}
}Get Group
GET /api/groups/{id}
Response:
{
"id": 1,
"name": "Laravel Developers",
"description": "Full description...",
"rules": "Group rules...",
"type": "public",
"owner": {...},
"admins": [...],
"members_count": 456,
"posts_count": 892,
"is_member": true,
"is_admin": false,
"created_at": "2024-01-01T00:00:00Z"
}Create Group
POST /api/groups
{
"name": "My New Group",
"description": "Group description",
"type": "public", // public, private, secret
"rules": "Optional group rules"
}
Response:
{
"id": 15,
"name": "My New Group",
...
}Join Group
POST /api/groups/{id}/join
Response:
{
"member": true,
"status": "joined" // or "pending" for private groups
}Leave Group
DELETE /api/groups/{id}/join
Response:
{
"member": false
}Messages
List Conversations
GET /api/conversations
Response:
{
"data": [
{
"id": 1,
"participants": [
{"id": 2, "name": "Jane Smith", "avatar_url": "..."}
],
"last_message": {
"content": "Sounds good!",
"sender_id": 2,
"created_at": "2024-03-15T15:30:00Z"
},
"unread_count": 2,
"updated_at": "2024-03-15T15:30:00Z"
}
],
"meta": {...}
}Get Conversation Messages
GET /api/conversations/{id}/messages
Response:
{
"data": [
{
"id": 1,
"content": "Hey, how are you?",
"sender": {"id": 1, "name": "John Doe"},
"read_at": "2024-03-15T15:31:00Z",
"created_at": "2024-03-15T15:30:00Z"
}
],
"meta": {...}
}Send Message
POST /api/conversations/{id}/messages
{
"content": "Hello there!"
}
Response:
{
"id": 42,
"content": "Hello there!",
"sender": {...},
"created_at": "2024-03-15T16:00:00Z"
}Start New Conversation
POST /api/conversations
{
"recipient_id": 2,
"content": "Hi, I wanted to reach out..."
}
Response:
{
"conversation_id": 15,
"message": {...}
}Notifications
List Notifications
GET /api/notifications
Query Parameters:
- unread: true/false
- type: mention, comment, like, follow, message
Response:
{
"data": [
{
"id": "abc123",
"type": "mention",
"data": {
"user": {"id": 2, "name": "Jane Smith"},
"post": {"id": 5, "title": "..."}
},
"read_at": null,
"created_at": "2024-03-15T12:00:00Z"
}
],
"meta": {...},
"unread_count": 5
}Mark as Read
POST /api/notifications/{id}/read
Response:
{
"read_at": "2024-03-15T12:05:00Z"
}Mark All as Read
POST /api/notifications/read-all
Response:
{
"message": "All notifications marked as read",
"count": 5
}Search
GET /api/search?q=query&type=all
Query Parameters:
- q: Search query (required)
- type: all, posts, users, groups
- page: Page number
- per_page: Results per page
Response:
{
"posts": {
"data": [...],
"total": 25
},
"users": {
"data": [...],
"total": 10
},
"groups": {
"data": [...],
"total": 5
}
}Error Responses
The API uses standard HTTP status codes:
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Validation Error |
| 429 | Rate Limited |
| 500 | Server Error |
Error response format:
{
"message": "The given data was invalid.",
"errors": {
"title": ["The title field is required."],
"content": ["The content must be at least 10 characters."]
}
}Webhooks
Configure webhooks to receive real-time notifications:
POST /api/webhooks
{
"url": "https://your-app.com/webhook",
"events": ["post.created", "comment.created", "user.registered"],
"secret": "your-webhook-secret"
}
Response:
{
"id": 1,
"url": "https://your-app.com/webhook",
"events": [...],
"created_at": "..."
}Webhook Payload
{
"event": "post.created",
"timestamp": "2024-03-15T12:00:00Z",
"data": {
"post": {...}
},
"signature": "sha256=..."
}SDKs & Libraries
Coming Soon: Official SDKs for JavaScript, PHP, and Python are in development.
// JavaScript example (fetch)
const response = await fetch('https://your-community.com/api/posts', {
headers: {
'Authorization': 'Bearer ' + token,
'Accept': 'application/json'
}
});
const posts = await response.json();