# Quickstart Guide

{% hint style="info" %}
**BUSINESS ACCESS ONLY**: The Publer API is currently available exclusively to Publer Business users.
{% endhint %}

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 Business Publer 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 Business plan access.
2. Go to **Settings → Access & Login →** **API Keys**.
3. Click **Create API Key**.
4. Enter a descriptive name, then select scopes:
   * `workspaces`
   * `accounts`
   * `posts`
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:

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

#### **Sample** Response

```json
[
    {
      "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:

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

#### Expected Response

```json
{
  "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:

```bash
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:

```json
{
  "job_id": "68176fa0f0eb419444bee686"
}
```

### Step 5: Poll Job Status

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

```bash
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

```json
{
  "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:

```json
{
  "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:

```bash
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

```json
{
  "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**](https://publer.com/docs/posting/create-posts/content-types) (photos, videos, links, polls)
* Dive into [**Media Handling**](https://publer.com/docs/posting/create-posts/media-handling) and upload workflows
* Learn about [**Publishing Methods**](https://publer.com/docs/posting/create-posts/publishing-methods) (drafts, recurring posts)
* Review [**Network Reference**](https://publer.com/docs/posting/create-posts/networks) for platform-specific limits

For full API details, see the [**API Reference**](https://publer.com/docs/api-reference).\
For assistance, contact <support@publer.com>.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://publer.com/docs/getting-started/quickstart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.