The Posts Create endpoints let you asynchronously schedule, draft, or immediately publish content across one or more social networks. Submit a batch request, receive a job ID, then poll for completion.

### Requirements

- **Authentication**: Bearer API token
- **Scopes**: `posts, media`
- **Headers**:
  - `Authorization: Bearer-API YOUR_API_KEY`
  - `Publer-Workspace-Id: YOUR_WORKSPACE_ID`

### Core Concepts

#### Asynchronous Workflow

```
Submit Request  →  Receive Job ID  →  Poll Job Status  →  Processing Complete
```

1. **Submit Request** to `/posts/schedule` or `/posts/schedule/publish`
2. **Receive**`{ "job_id": "…" }`
3. **Poll**`/job_status/{job_id}` until `status: "completed"`
4. **Handle** results or errors

#### Common Request Structure

All create requests share this shape:

```
{
  "bulk": {
    "state": "[publishing_method]",
    "posts": [
      {
        "networks": {
          "[network_provider]": {
            "type": "[content_type]",
            "text": "Post content",
            // other network-specific fields
          }
        },
        "accounts": [
          {
            "id": "ACCOUNT_ID"
            // Additional parameters based on publishing method
            }
        ],
        // optional: recycling, recurring, labels, etc.
      }
    ]
  }
}
```

- **bulk**: batch container
- **state**: how to handle content (see **Publishing Methods**)
- **posts**: array of post definitions
- **networks**: per-network content config
- **accounts**: target profiles with scheduling overrides

### Endpoints

| Endpoint                           | Purpose                                                   | Result                     |
|-----------------------------------|----------------------------------------------------------|---------------------------|
| `/api/v1/posts/schedule`          | Schedule posts for future publication including drafts    | Scheduled post or draft   |
| `/api/v1/posts/schedule/publish`  | Publish content immediately                               | Published post            |
| `/api/v1/job_status/{job_id}`     | Check status of submitted job                             | Job status                |

### Publishing Methods

The `state` parameter determines how your content will be handled:

| State            | Description                                           | Additional Parameters                  |
|------------------|------------------------------------------------------|---------------------------------------|
| `scheduled`      | Schedule for specific date/time                      | `scheduled_at` (ISO timestamp)       |
| `draft`, `draft_private`, `draft_public` | Save as draft                                  | None required                       |
| `scheduled` + `auto: true` | Use AI-powered auto-scheduling                   | `range.start_date`, `range.end_date`|
| `scheduled` + `recycling` | Reuse content multiple times                 | `recycling.gap`, `recycling.expire_count`|
| `recurring`     | Create repeating posts                                | `recurring.repeat`, `recurring.days_of_week`|

### Content Types

The `type` parameter specifies the content format:

| Type       | Description                  | Required Properties                  |
|------------|------------------------------|--------------------------------------|
| `status`   | Text-only post               | `text`                               |
| `photo`    | Image post                   | `text`, `media` array               |
| `video`    | Video post                   | `text`, `media` array               |
| `link`     | Link post with preview       | `text`, `url`                       |
| `carousel`  | Multi-image post             | `text`, `media` array               |
| `pdf`      | PDF document (LinkedIn)     | `text`, `media` array               |

### Network Providers

Supported platforms and their keys under `networks`:

`facebook`, `instagram`, `twitter`, `linkedin`, `pinterest`, `youtube`, `tiktok`, `google`, `wordpress_basic`, `wordpress_oauth`, `telegram`, `mastodon`, `threads`, `bluesky`.

### Job Status

Poll your job with:

```
GET /api/v1/job_status/{job_id}
```

**Response**:

```
{
  "status": "working|completed|failed",
  "payload": { /* results or errors */ }
}
```

### Common Patterns

#### Network-Specific Content

To customize content for specific platforms:

```
{
"networks": {
  "facebook": {
    "type": "status",
    "text": "Facebook simple status update"
  },
  "twitter": {
    "type": "status",
    "text": "Twitter/X specific content with #hashtags"
  },
  "linkedin": {
    "type": "status",
    "text": "Longer, more professional content for LinkedIn audience"
  }
},
"accounts": [
  {
    "id": "66db83154e299efa19a2d8eb",
    "scheduled_at": "2025-05-15T14:30:00Z"
  },
  {
    "id": "66e973ac4e299e531f5dc034",
    "scheduled_at": "2025-05-15T15:00:00Z"
  },
  {
    "id": "66e973ac4e299e531f4hc034",
    "scheduled_at": "2025-05-15T15:00:00Z"
  }
]
}
```

#### Media References

Media files must be pre-uploaded and referenced by ID:

```
"media": [
  {
    "id": "66fba4234e299e531f5dc100",
    "type": "image",
    "alt_text": "Optional accessibility description"
  }
]
```

### Next Steps

This overview covers the essential concepts for creating posts with the Publer API. For detailed information about specific features, refer to:

- [Publishing Methods](https://publer.com/docs/posting/create-posts/publishing-methods): Complete documentation of all publishing options
- [Content Types](https://publer.com/docs/posting/create-posts/content-types): Detailed guide to content formats and requirements
- [Media Handling](https://publer.com/docs/posting/create-posts/media-handling): Information about uploading and managing media
- [Network Reference](https://publer.com/docs/posting/create-posts/networks): Platform-specific capabilities and limitations