publer-api（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

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.