---
title: Schedule API - Automate Social Post Scheduling
description: Schedule, draft, and publish social posts to LinkedIn, Instagram, TikTok, and Threads with the PostNitro Embed API. Authentication, conventions, response formats, and endpoint reference.
canonical: https://postnitro.ai/docs/embed/api/schedule
---

# Schedule API

The Schedule API lets you create, list, read, update, and delete **scheduled
(and draft) social posts** across LinkedIn, Instagram, TikTok, and Threads from
your own application using your PostNitro **Embed API key**.

These endpoints are a thin, authenticated layer over PostNitro's internal Planner
service. Your request is validated for shape, scoped to the workspace attached to
your API key, and forwarded to PostNitro for processing.

## Endpoints

| Method | Path | Description |
| --- | --- | --- |
| `GET` | [`/schedule`](https://postnitro.ai/docs/embed/api/schedule/list-scheduled-posts) | List scheduled posts in a date range |
| `POST` | [`/schedule`](https://postnitro.ai/docs/embed/api/schedule/create-scheduled-post) | Create a scheduled post or draft |
| `GET` | [`/schedule/:id`](https://postnitro.ai/docs/embed/api/schedule/get-scheduled-post) | Fetch a single scheduled post |
| `PUT` | [`/schedule/:id`](https://postnitro.ai/docs/embed/api/schedule/update-scheduled-post) | Update a scheduled post |
| `DELETE` | [`/schedule/:id`](https://postnitro.ai/docs/embed/api/schedule/delete-scheduled-post) | Delete a scheduled post |

## Base URL

All paths are relative to your Embed API base URL, e.g.:

```cURL
https://embed-api.postnitro.ai/schedule
```

## Authentication

Every request must include your Embed API key in the `embed-api-key` header
(an `authorization` header is also accepted):

```
embed-api-key: <YOUR_EMBED_API_KEY>
```

Your key resolves the **organization**, **workspace**, and **user** the post
belongs to. You never send `workspaceId` or `organizationId` — they are derived
from the key server-side.

| Condition | Status | Body |
| --- | --- | --- |
| No key supplied | `401` | `{ "status": false, "message": "Unauthorized" }` |
| Key not found / not an API key | `401` | `{ "status": false, "message": "Unable to find embed details, please check your Embed API key..." }` |
| No workspace attached to key | `401` | `{ "status": false, "message": "Unable to find workspace details, please attach a workspace to this API key." }` |
| No active/paid plan | `402` | `{ "status": false, "message": "Embed API requires a paid main plan with the API Credits add-on, or an active Embed API subscription." }` |

## Request & response format

- All request bodies (`POST`, `PUT`) are JSON. Set `Content-Type: application/json`.
- All successful responses are JSON wrapped in a standard envelope:

```jsonc
{
  "success": true,
  "message": "Scheduled post created",   // present on create/update/delete
  "data": { /* endpoint-specific payload */ }
}
```

## Error format

There are two error shapes you may receive.

**1. Request-shape validation (handled at the Embed API edge)** — returns `422`:

```json
{
  "status": false,
  "message": "Status must be 'DRAFT' or 'SCHEDULED'"
}
```

**2. Processing / business-rule errors (relayed from PostNitro)** — the upstream
status code is preserved where available (otherwise `500`):

```jsonc
{
  "success": false,
  "message": "Design not found.",   // human-readable reason
  "error": { /* upstream details, or the message string */ }
}
```

See each endpoint page for the specific validation and business rules that apply.

## Statuses

- **Post status** (`status`): `"DRAFT"` or `"SCHEDULED"`.
- **Per-account status** (`socialAccounts[].status`): `"DRAFT"` when the post is a
  draft, otherwise `"PENDING"` on create/update. The publishing pipeline later
  updates this to values such as published/failed.

## Shared concepts

The create and update endpoints share the same request body and the same
per-platform settings rules. Rather than repeat them, see:

- [Scheduled-post object](https://postnitro.ai/docs/embed/api/schedule/scheduled-post-object) — the shape returned by
  every endpoint (note: response uses `scheduledFor` and `postContents`)
- [Request body reference](https://postnitro.ai/docs/embed/api/schedule/create-scheduled-post#request-body) — full body shape
- [Platform settings & conditional rules](https://postnitro.ai/docs/embed/api/schedule/platform-settings) — when each
  `*PostSettings` object is required and how its fields are validated