🎁 Get the FREE AI Skills Starter Guide — Subscribe →
BytesAgainBytesAgain
BytesAgain › Skills › Publer API
🦀 ClawHub

Publer API

by @gjeka

Use this skill whenever the user wants to interact with the Publer API — including managing social media posts (create, schedule, update, delete, approve), b...

Versionv1.0.0
Downloads889
#social-media#legal#automation
TERMINAL
clawhub install publer-api

📖 About This Skill

name: publer-api description: > Use this skill whenever the user wants to interact with the Publer API — including managing social media posts (create, schedule, update, delete, approve), browsing or uploading media, viewing workspaces and connected social accounts, or retrieving analytics. Trigger this skill any time the user mentions Publer, wants to schedule or manage posts across social platforms via Publer, asks about Publer analytics or insights, needs to work with the Publer media library, or wants to analyze competitors or hashtag performance via Publer. Also trigger when the user asks to automate social media workflows that involve Publer, even if they don't explicitly say "Publer API".

Publer API Skill

This skill enables you to interact with all Publer API endpoints.

Business plan required. The Publer API is only available to Business plan users.

Setup

Base URL: https://app.publer.com/api/v1

Required headers on almost every request: 

Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Content-Type: application/json

Note: Bearer-API (not Bearer) is the correct format.

If the user hasn't provided their API key, ask for it before making any calls. Never hardcode or expose API keys.

API key scopes: workspaces, accounts, posts, media, analytics

Quick Reference: All Endpoints

| Area | Method | Endpoint | |---|---|---| | Users | GET | /users/me | | Workspaces | GET | /workspaces | | Accounts | GET | /accounts | | Posts | GET | /posts | | Posts — Schedule/Draft | POST | /posts/schedule | | Posts — Publish Now | POST | /posts/schedule/publish | | Posts — Update | PUT | /posts/{id} | | Posts — Delete | DELETE | /posts | | Job Status | GET | /job_status/{job_id} | | Media — List | GET | /media | | Media — Direct Upload | POST | /media | | Media — URL Upload | POST | /media/from-url | | Media Options | GET | /workspaces/{workspace_id}/media_options | | Analytics — Charts List | GET | /analytics/charts | | Analytics — Chart Data | GET | /analytics/:account_id/chart_data | | Analytics — Post Insights | GET | /analytics/:account_id/post_insights | | Analytics — Hashtag Insights | GET | /analytics/:account_id/hashtag_insights | | Analytics — Hashtag Posts | GET | /analytics/:account_id/hashtag_performing_posts | | Analytics — Best Times | GET | /analytics/:account_id/best_times | | Analytics — Members | GET | /analytics/members | | Competitors — List | GET | /competitors/:account_id | | Competitors — Analytics | GET | /competitors/:account_id/analytics |

For full request/response shapes, read references/api-reference.md.

Workflow

1. Identify the intent

Map the user's request to one or more API calls from the table above.

2. Gather required parameters

  • Workspace ID: Needed for most calls. If unknown, call GET /workspaces first.
  • Account IDs: Needed for post creation. If unknown, call GET /accounts.
  • Scheduled posts: scheduled_at must be ISO 8601 with timezone, at least 1 minute in the future.
  • Analytics: Most endpoints need from/to date range (YYYY-MM-DD). They are co-required.
  • Media: Must be uploaded first via /media or /media/from-url, then referenced by ID in posts.

    • 3. Make the API call

    Use the correct HTTP method and headers. POST/PUT use Content-Type: application/json. Media direct upload uses multipart/form-data.

    4. Handle async operations

    Post creation and URL media uploads are asynchronous:
  • Response returns { "success": true, "data": { "job_id": "..." } }
  • Poll GET /job_status/{job_id} until status is "complete" or "failed"
  • Check payload.failures even on "complete" — partial failures are possible

    • 5. Interpret the response

  • 2xx — success. Parse and present relevant fields clearly.
  • 401 — ask user to verify API key and confirm Bearer-API format.
  • 403 — check required scope is enabled, and Publer-Workspace-Id header is present.
  • 404 — resource ID is wrong; confirm with user.
  • 422 — surface the errors[] array to user and ask them to correct input.
  • 429 — rate limited (100 req/2 min); wait for X-RateLimit-Reset, use exponential backoff.
  • 5xx — Publer server error; suggest retry.

    • Common Workflows

    Schedule a post

    1. If workspace/account IDs unknown: GET /workspaces then GET /accounts 2. POST /posts/schedule with state: "scheduled", network content, and scheduled_at per account 3. Poll GET /job_status/{job_id} until complete 4. Confirm back: platform(s), scheduled time, text preview

    Publish immediately

    Same as above but use POST /posts/schedule/publish and omit scheduled_at.

    Cross-post with platform-specific content

    Use multiple keys under networks with per-platform text/type: 
    "networks": {
  "facebook": { "type": "status", "text": "Longer Facebook copy..." },
  "twitter": { "type": "status", "text": "Short tweet #hashtag" },
  "linkedin": { "type": "status", "text": "Professional LinkedIn copy..." }
}

    Upload and attach media

    1. POST /media (multipart) for direct upload, or POST /media/from-url for URL import 2. Check validity object in response for network compatibility 3. Reference media.id in the media[] array inside the network object when creating post

    List and review scheduled posts

    1. GET /posts?state=scheduled 2. Display as readable list: date, network, text preview 3. Offer to edit (PUT /posts/{id}) or delete (DELETE /posts?post_ids[]=...) on request

    Fetch analytics

    1. For account-level charts: GET /analytics/charts to get available IDs, then GET /analytics/:account_id/chart_data?chart_ids[]=...&from=...&to=... 2. For per-post performance: GET /analytics/:account_id/post_insights?from=...&to=... 3. For hashtag performance: GET /analytics/:account_id/hashtag_insights 4. For best posting times: GET /analytics/:account_id/best_times?from=...&to=...

    Competitor analysis

    1. GET /competitors/:account_id to list competitors 2. GET /competitors/:account_id/analytics for aggregate metrics 3. Use competitors=true&competitor_id=... on post insights and best times endpoints for deeper comparison

    Key Notes & Edge Cases

  • Auth header format: Bearer-API YOUR_KEY — not Bearer
  • Workspace in header vs path: Most endpoints use Publer-Workspace-Id header. Exception: GET /workspaces/{workspace_id}/media_options uses workspace ID in the path.
  • /users/me and /workspaces do not require the workspace header.
  • Pagination: 0-based page param throughout. Post insights and hashtag insights return 10 per page.
  • Date format: ISO 8601 with timezone for timestamps; YYYY-MM-DD for analytics date ranges.
  • default network key: Use "default" as the network to apply same content to all accounts.
  • Threads: Cannot schedule for specific times via API.
  • Analytics data freshness: Metrics auto-sync ~every 24h. Not real-time.
  • Competitor sort_type: Lowercase asc/desc — unlike post/hashtag insights which use ASC/DESC.
  • reach field: May be omitted in members analytics and competitor analytics for unsupported networks — handle gracefully.

    • Reference Files

  • references/api-reference.md — Full endpoint docs with all request/response shapes, field enums, media specs, daily post limits, and error handling. Read this when you need exact field names, response shapes, or need to handle a case not covered above.

    • ⚙️ Configuration

    Base URL: https://app.publer.com/api/v1

    Required headers on almost every request: 

    Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Content-Type: application/json

    Note: Bearer-API (not Bearer) is the correct format.

    If the user hasn't provided their API key, ask for it before making any calls. Never hardcode or expose API keys.

    API key scopes: workspaces, accounts, posts, media, analytics