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: INLINECODE0

Required headers on almost every request:
CODEBLOCK0

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

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

Workflow

1. Identify the intent

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

4. Handle async operations

• - Response returns INLINECODE40
• Poll GET /job_status/{job_id} until status is "complete" or INLINECODE44
• 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. 1. If workspace/account IDs unknown: GET /workspaces then INLINECODE52
2. INLINECODE53 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

Cross-post with platform-specific content

Upload and attach media

1. 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. 1. INLINECODE65
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. 1. For account-level charts: GET /analytics/charts to get available IDs, then INLINECODE69
2. For per-post performance: INLINECODE70
3. For hashtag performance: INLINECODE71
4. For best posting times: INLINECODE72

Competitor analysis

1. 1. GET /competitors/:account_id to list competitors
2. INLINECODE74 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 INLINECODE77
• 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.