# Introduction

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

### What Is the Publer API?

A RESTful JSON interface for automating social media workflows—scheduling, publishing, media management, and analytics—across multiple networks.

### Base URL

All endpoints share this root URL:

```http
https://app.publer.com/api/v1/
```

### Authentication

Include your API key and workspace ID on almost every request:

```http
Authorization: Bearer-API YOUR_API_KEY
Publer-Workspace-Id: YOUR_WORKSPACE_ID
Content-Type: application/json
```

### Request Format

#### GET

Use query parameters for filters and pagination:

```http
GET /posts?state=scheduled&from=2025-04-20
```

#### POST, PUT, PATCH

Send JSON in the request body:

```json
POST /posts
{
  "bulk": {
    "state": "scheduled",
    "posts": [ … ]
  }
}
```

#### DELETE

No request body is required (unless otherwise noted):

```http
DELETE /posts/{post_id}
```

### Response Format

All responses are JSON.

#### Success

* **Synchronous endpoints** return the requested resource or collection.
* **Asynchronous endpoints** (e.g., post creation) return a `job_id`:

  ```json
  { "job_id": "6810dec617eae6d55d7a5e5b" }
  ```

#### Error

* Status codes indicate general error type (4xx, 5xx).
* The response body contains an `errors` array:

  ```json
  { "errors": ["Detailed error message"] }
  ```

#### Common HTTP Status Codes

* 200 OK
* 201 Created
* 202 Accepted (async)
* 400 Bad Request
* 401 Unauthorized
* 403 Forbidden
* 404 Not Found
* 429 Too Many Requests
* 500 Internal Server Error

### Versioning

Current version: **v1** (in the URL path).\
We follow [Semantic Versioning](https://semver.org/). Breaking changes only occur on MAJOR version bumps; you will be notified in advance.

### Asynchronous Operations

1. Submit your request → **202 Accepted** + `{"job_id": "…"}`
2. Poll the job status endpoint until complete:

   ```sh
   GET /job_status/{job_id}
   ```

   ```json
   {
     "status": "completed",
     "payload": { "failures": {} }
   }
   ```

### Date & Time

All timestamps use ISO 8601 with timezone:

```
YYYY-MM-DDThh:mm:ss±hh:mm
```

Example: `2025-05-04T14:58:35+00:00`

### Privacy & Security

* Always use HTTPS.
* Sensitive fields may be redacted.
* Adhere to least-privilege scope selection.

### Next Steps

* [Users API](https://publer.com/docs/api-reference/users)
* [Workspaces API](https://publer.com/docs/api-reference/workspaces)
* [Accounts API](https://publer.com/docs/api-reference/accounts)
* [Posts API](https://publer.com/docs/api-reference/posts)

For implementation examples, see the Quickstart Guide and sections on creating content, media handling, and network-specific formats.