Connector Protocol v1.1.0

The HQ Connector Protocol is a REST API contract that every node plugin must implement. The Hub pushes content to nodes through these endpoints.

Base URL

https://{your-site}/api/connector

Authentication

All requests (except /ping) require a Bearer token in the Authorization header:

Authorization: Bearer node_your_token_here

Tokens are created via the CLI or the Hub admin panel. Each token has scopes:

Endpoints

Health Check

GET /api/connector/ping

Returns status, node info, and the authenticated hub ID.

List Posts

GET /api/connector/posts?limit=50

Returns a list of recently pushed posts. Max limit: 200.

Create / Upsert Post

POST /api/connector/posts

Creates a new post or updates an existing one if hub_post_id already exists.

{
    "hub_post_id": 456,
    "title": "My Article",
    "slug": "my-article",
    "body_html": "<p>Content here</p>",
    "meta": {
        "title": "SEO Title",
        "description": "Meta description",
        "keywords": ["php", "laravel"],
        "json_ld": {"@type": "Article"}
    },
    "featured_image": "https://cdn.example.com/cover.jpg",
    "published": true
}

Update Post

PATCH /api/connector/posts/{node_post_id}

Partial update. All fields optional.

Delete Post

DELETE /api/connector/posts/{node_post_id}

Returns 204 on success.

Upload Media

POST /api/connector/media

POST /api/connector/posts/{node_post_id}/media

Upload images as multipart/form-data. The attach endpoint links media to a post.

Error Format

{
    "error": {
        "code": "unauthorized",
        "message": "Missing bearer token."
    }
}