> For the complete documentation index, see [llms.txt](https://publer.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://publer.com/docs/posting/update-posts/unpublished-posts.md).

# Unpublished Posts

Once a post exists, you can move it, promote it, change its state, or delete it — without rebuilding the payload. These endpoints complement `PUT /api/v1/posts/{id}`, which only changes `text` and `title`.

#### Requirements

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

{% hint style="info" %}
All four endpoints require that the API key's user is the **creator** of the post. A key belonging to a different member of the same workspace can read the post but not modify it.
{% endhint %}

### **Reschedule Post**

Move a scheduled post to a new time.

```http
PUT /api/v1/posts/{id}/reschedule
```

## Reschedule Post

> Reschedules a post to a new date and time. This may trigger approval workflows depending on workspace settings.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Posts","description":"Endpoints for managing social media posts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}}},"paths":{"/posts/{id}/reschedule":{"put":{"summary":"Reschedule Post","description":"Reschedules a post to a new date and time. This may trigger approval workflows depending on workspace settings.","tags":["Posts"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace containing the post","required":true},{"schema":{"type":"string"},"name":"id","in":"path","description":"ID of the post to reschedule","required":true}],"responses":{"200":{"description":"Post successfully rescheduled","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the post"},"state":{"type":"string","description":"Current state of the post"},"scheduled_at":{"type":"string","format":"date-time","description":"New scheduled date and time for the post"},"details":{"type":"object","description":"Additional details about the post"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of error messages"}}}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of error messages"}}}}}},"422":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"}}}}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["scheduled_at"],"properties":{"scheduled_at":{"type":"string","format":"date-time","description":"New date and time for the post in ISO 8601 format"}}}}},"description":"New scheduled time for the post","required":true}}}}}
```

Example:

```json
{ "post": { "scheduled_at": "2026-10-14T09:30:00Z" } }
```

***

### **Publish Post Now**

Publish a draft, scheduled or failed post immediately.

```http
POST /api/v1/posts/{id}/publish_now
```

## Publish Post Now

> Immediately publishes a scheduled/draft post to its associated social media account.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Posts","description":"Endpoints for managing social media posts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}}},"paths":{"/posts/{id}/publish_now":{"post":{"summary":"Publish Post Now","description":"Immediately publishes a scheduled/draft post to its associated social media account.","tags":["Posts"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace containing the post","required":true},{"schema":{"type":"string"},"name":"id","in":"path","description":"ID of the post to publish","required":true}],"responses":{"200":{"description":"Post publishing job started successfully","content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","description":"ID of the background job that will publish the post"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of error messages"}}}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"type":"object","properties":{"errors":{"type":"array","items":{"type":"string"},"description":"List of error messages"}}}}}}}}}}}
```

Returns `{ "job_id": "..." }`. Poll Job Status for the outcome. Retrying a `failed` post clears its upload checkpoints first, so the publish starts cleanly.

***

### **Change Post State**

Promote a draft to scheduled, or move a post back to draft.

```http
PUT /api/v1/posts/{id}/state
```

## Change Post State

> Changes the state of a post, for example promoting a draft to scheduled.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Posts","description":"Endpoints for managing social media posts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"PostDetail":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the post"},"text":{"type":"string","description":"Post text content"},"state":{"type":"string","description":"Current state of the post"},"type":{"type":"string","description":"Type of post"},"account_id":{"type":"string","description":"ID of the social account"},"account":{"type":"object","description":"Details of the social account","properties":{"id":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"picture":{"type":"string"}}},"user":{"type":"object","description":"User who created the post","properties":{"id":{"type":"string"},"name":{"type":"string"},"picture":{"type":"string"}}},"scheduled_at":{"type":"string","description":"Scheduled publication time"},"created_at":{"type":"string","description":"Creation timestamp"},"updated_at":{"type":"string","description":"Last update timestamp"},"post_link":{"type":"string","description":"Link to the published post on the social network"},"media":{"type":"array","description":"Media items attached to the post","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"url":{"type":"string"},"alt_text":{"type":"string"}}}},"link":{"type":"object","description":"Link details for link posts","properties":{"url":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"image_url":{"type":"string"}}},"labels":{"type":"array","description":"Labels assigned to this post","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}}},"auto":{"type":"boolean","description":"Whether this post was auto-scheduled"},"recycling":{"type":"object","description":"Recycling settings if applicable","properties":{"solo":{"type":"boolean"},"gap":{"type":"integer"},"gap_freq":{"type":"string"},"start_date":{"type":"string"},"expire_count":{"type":"integer"}}},"recurring":{"type":"object","description":"Recurring settings if applicable","properties":{"frequency":{"type":"string"},"repeat_every":{"type":"integer"},"weekdays":{"type":"array","items":{"type":"string"}},"start_date":{"type":"string"}}}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"422ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/posts/{id}/state":{"put":{"summary":"Change Post State","tags":["Posts"],"description":"Changes the state of a post, for example promoting a draft to scheduled.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the resource"},{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"ID of the post"}],"responses":{"200":{"description":"Post updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostDetail"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"422":{"description":"Unprocessable Entity - invalid state transition","content":{"application/json":{"schema":{"$ref":"#/components/schemas/422ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"post":{"type":"object","required":["state"],"properties":{"state":{"type":"string","description":"Target state, for example scheduled, draft_private or draft_public"}}}}}}},"required":true,"description":"New state"}}}}}
```

Example:

```json
{ "post": { "state": "scheduled" } }
```

{% hint style="info" %}
This is the intended "build as a draft, release later" flow: create with `state: "draft"`, verify with `GET /api/v1/posts/{id}`, then flip to `scheduled`.
{% endhint %}

***

### **Delete Post**

Delete one post.

```http
DELETE /api/v1/posts/{id}/destroy_single
```

{% hint style="info" %}
Use this to remove a **single** post. `DELETE /api/v1/posts` remains the bulk operation, taking `post_ids[]` or state filters.
{% endhint %}

#### Notes

* A post that does not exist returns **422**, not 404. A post in another workspace returns **403**.
* Posts already in the publishing queue cannot be rescheduled, published, or edited — wait for the queue to drain.
* Posts published under an approval workflow cannot be deleted by editors.

#### Related Resources

* Get Post — Read a single post back
* [Updating Posts](/docs/posting/update-posts.md) — Change text and title
* [Deleting Posts](/docs/posting/delete-posts.md) — Bulk deletion


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://publer.com/docs/posting/update-posts/unpublished-posts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.