Quickstart Guide

TOP AMBASSADOR AND ENTERPRISE ACCESS ONLY: The Publer API is currently available exclusively to Publer Ambassadors and Enterprise users.

This guide walks you through the core steps to integrate with Publer’s API in minutes. By the end, you’ll have published your first scheduled post.

Prerequisites

• A Top Publer Ambassador or Enterprise account

• Basic familiarity with HTTP/JSON APIs

• A command-line tool (curl) or API client (Postman, Insomnia)

Step 1: Generate an API Key

1. Sign in to Publer and verify you have Ambassador or Enterprise access.

2. Go to Settings → Access & Login → API Keys.

3. Click Create API Key.

4. Enter a descriptive name, then select scopes:

   • workspaces

   • posts

   • accounts

   • users

   • media

   • job_status

   • locations

5. Click Create.

6. Copy and store the key securely—this value will not be shown again.

Step 2: List Workspaces

Before making other requests, let's retrieve your workspaces. The workspace ID is required in the header for most API operations:

curl -X GET "https://app.publer.com/api/v1/workspaces" \
  -H "Authorization: Bearer-API YOUR_API_KEY"

Sample Response

[
    {
      "id": "5f8d7a62c9e77e001f36e3a1",
      "name": "My Primary Workspace",
      "role": "owner",
      "picture": "https://publer.io/uploads/workspaces/thumb_mini_workspace_123.png"
    },
    {
      "id": "60a2e45f9b3c8d002a4b7c32",
      "name": "Client Workspace",
      "role": "admin",
      "picture": "https://publer.io/uploads/workspaces/thumb_mini_workspace_456.png"
    }
]

Now you can use a workspace ID in your subsequent requests by including it in the header:

Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1

Step 3: List Social Accounts

Next, let's retrieve the social media accounts in your workspace. You'll need the account IDs to specify where to publish your posts:

curl -X GET "https://app.publer.com/api/v1/accounts" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Publer-Workspace-ID: 5f8d7a62c9e77e001f36e3a1"

Expected Response

{
  "accounts": [
    {
      "id": "63c675b54e299e9cf2b667ea",
      "name": "My Facebook Page",
      "provider": "facebook",
      "type": "page",
      "picture": "https://publer.io/uploads/accounts/thumb_mini_facebook_page.jpg",
      "status": "active"
    },
    {
      "id": "63c675d74e299e9cf2b667eb",
      "name": "Company LinkedIn Page",
      "provider": "linkedin",
      "type": "page",
      "picture": "https://publer.io/uploads/accounts/thumb_mini_linkedin_page.jpg",
      "status": "active"
    },
    {
      "id": "63c675e94e299e9cf2b667ec",
      "name": "Brand Twitter",
      "provider": "twitter",
      "type": "profile",
      "picture": "https://publer.io/uploads/accounts/thumb_mini_twitter.jpg",
      "status": "active"
    }
  ]
}

Make note of the account IDs as you'll need them to specify where to publish your content in the next step.

Step 4: Create a Scheduled Post

Make your first scheduled post with one API call:

curl -X POST "https://app.publer.com/api/v1/posts/schedule" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1" \
  -H "Content-Type: application/json" \
  -d '{
    "bulk": {
      "state": "scheduled",
      "posts": [
        {
          "networks": {
            // You need to provide the network provider as the key, e.g., facebook, twitter
            "facebook": {
              "type": "status", // Type of the post
              "text": "Status Update Post" // Text of the post
            }
          },
          "accounts": [
            {
              "id": "63c675b54e299e9cf2b667ea", // Id of the selected account
              "scheduled_at": "2025-09-06T14:16+02:00" // Scheduled time
            }
          ]
        }
      ]
    }
  }'

Sample Response

The API returns a job ID that you can use to check the status of your request:

{
  "job_id": "68176fa0f0eb419444bee686"
}

Step 5: Poll Job Status

Posts are created asynchronously. Use the returned job_id to check progress:

curl -X GET "https://app.publer.com/api/v1/job_status/68176fa0f0eb419444bee686" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Publer-Workspace-Id: 5f8d7a62c9e77e001f36e3a1"

Successful Job Response

{
  "status": "complete",
  "payload": {
    "failures": {}
  },
  "plan": {
    // other account-specific data
  }
}

Failed Job Response

If there's an error with your request, the response will include details about what went wrong:

{
  "status": "complete",
  "payload": {
    "failures":[
        {
          "account_id": "63c675b54e299e9cf2b667ea",
          "account_name": "Test Page",
          "provider": "facebook",
          "message": "There's another post at this time. A one minute gap is required between posts"
        }
    ]
  },
  "plan": {
    // other account-specific data
  }
}

Step 6: Verify Scheduled Posts

List your scheduled posts to confirm creation:

curl -X GET "https://app.publer.com/api/v1/posts?state=scheduled" \
  -H "Authorization: Bearer-API YOUR_API_KEY" \
  -H "Publer-Workspace-ID: 5f8d7a62c9e77e001f36e3a1"

Sample Response

{
  "posts": [
    {
      "id": "68176f0e8bee9dc9b0ce3427",
      "text": "Status Update Post for 2025-05-07!",
      "url": null,
      "title": null,
      "state": "scheduled",
      "type": "status",
      "account_id": "63c675b54e299e9cf2b667ea",
      "user": {
        "id": "5b1ec026db27977424e8599e",
        "name": "Business User",
        "picture": "https://publer.io/uploads/photos/thumb_mini_magick20250123-28707-otuw0w.png"
      },
      "scheduled_at": "2025-05-08T14:30:00.000+02:00",
      "post_link": null
    }
  ],
  "total": 1
}

Understanding the Workflow

1. Generate an API key

2. List workspaces → pick a workspace ID

3. List accounts → pick account IDs

4. Submit a post creation request

5. Poll job status until completed

6. Fetch posts to verify

This async pattern scales across multiple workspaces, accounts, and post types.

Next Steps

• Explore Content Types (photos, videos, links, polls)

• Dive into Media Handling and upload workflows

• Learn about Publishing Methods (drafts, recurring posts)

• Review Network Reference for platform-specific limits

For full API details, see the API Reference. For assistance, contact [email protected].