ConnectHub API Reference

Overview

The ConnectHub API follows REST conventions. Resources are nested by scope, and HTTP verbs indicate the action to perform. Pagination is handled via cursor-based navigation for large datasets.

{
  "success": true,
  "data": { ... },
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true
  }
}

Authentication

Authenticate your requests using Bearer tokens. Include the token in the `Authorization` header for all protected endpoints.

Exchange your application credentials for an access token.

curl -X POST https://api.connecthub.com/v1/auth/token \\
  -H "Content-Type: application/json" \\
  -d '{"client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_SECRET"}'

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Users

Manage user profiles, preferences, and account settings.

Retrieve a paginated list of users matching query parameters.

Create a new user account.

{
  "username": "@jane_dev",
  "email": "jane@example.com",
  "display_name": "Jane Developer",
  "bio": "Building the future of social.",
  "avatar_url": null
}

Posts

Create, retrieve, and manage content posts across the platform.

Fetch posts from the user's feed or a specific community.

Publish a new post with media attachments.

{
  "content": "Just launched our new API! 🚀 #connecthub #developer",
  "visibility": "public",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.connecthub.com/media/img_8x2.png"
    }
  ]
}

Error Handling

ConnectHub uses standard HTTP status codes. Error responses include a structured body for programmatic handling.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The username field is required.",
    "details": [
      {
        "field": "username",
        "issue": "Missing required field"
      }
    ]
  }
}

Webhooks

Subscribe to real-time events like new follows, post interactions, or community joins. Configure your endpoint URL and verify signatures using the `X-ConnectHub-Signature` header.

Rate Limits

API calls are limited to 100 requests per minute per token. Headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` are included in every response.