> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Postiz API reference

> API reference for the Postiz plugin in Corsair: every `postiz.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Analytics

### platform

`analytics.platform`

Read one channel's analytics rows for a period

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.analytics.platform({ integration: 'cm4ean69r0003w8w1cdomox9n', date: '30' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `integration` | `string` | Yes | The integration id to read analytics for. |
| `date` | `string` | Yes | How many days to look back, such as `7`, `30` or `90`. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `analytics` | `object[]` | Yes | — |

> [accordion] analytics full type
>
> ```ts theme={null}
> {
>   label?: string | null,
>   percentageChange?: number | null,
>   data?: {
>     total?: string | number | null,
>     date?: string | null
>   }[] | null
> }[]
> ```

***

## Integrations

### findSlot

`integrations.findSlot`

Read a channel's next free posting slot

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.integrations.findSlot({ id: 'cm4ean69r0003w8w1cdomox9n' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The integration id whose posting schedule to read. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `date` | `string` | Yes | The next free slot, as an ISO 8601 UTC timestamp. |

***

### isConnected

`integrations.isConnected`

Confirm the API key is valid and the workspace is reachable

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.integrations.isConnected({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `connected` | `boolean` | Yes | True when the key is valid and the workspace is reachable. |

***

### list

`integrations.list`

List the connected channels, optionally narrowed to one customer group

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.integrations.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `group` | `string` | No | Only channels assigned to this customer (group) id. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `integrations` | `object[]` | Yes | — |

> [accordion] integrations full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null,
>   identifier?: string | null,
>   picture?: string | null,
>   disabled?: boolean | null,
>   profile?: string | null,
>   customer?: {
>     id?: string | null,
>     name?: string | null
>   } | null
> }[]
> ```

***

## Media

### list

`media.list`

Page through the organization's media library, optionally filtered by file name

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.media.list({ page: 1 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number, starting at 1. The library returns 18 files per page. |
| `search` | `string` | No | Case-insensitive filter on the original file name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `pages` | `number \| null` | No | The total number of pages. |
| `results` | `object[]` | Yes | — |

> [accordion] results full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null,
>   originalName?: string | null,
>   path?: string | null,
>   thumbnail?: string | null,
>   alt?: string | null,
>   createdAt?: string | null
> }[]
> ```

***

### uploadFromUrl

`media.uploadFromUrl`

Copy a file from a public URL into the media library, for use as a post attachment

**Risk:** `write`

```ts theme={null}
await corsair.postiz.api.media.uploadFromUrl({ url: 'https://example.com/image.png' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | A public http(s) URL Postiz downloads the file from. |
| `adjust` | `boolean` | No | Resize and re-encode the file to the platforms' limits after the upload. Runs in the background; the result's `status` is `processing` until it is done. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The uploaded media id. |
| `name` | `string \| null` | No | — |
| `path` | `string` | Yes | The hosted URL of the file. |
| `organizationId` | `string \| null` | No | — |
| `createdAt` | `string \| null` | No | — |
| `updatedAt` | `string \| null` | No | — |
| `status` | `string \| null` | No | `processing` while `adjust` runs, otherwise `ready`. |

***

## Notifications

### list

`notifications.list`

Page through the organization notifications, newest first

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.notifications.list({ page: 0 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `page` | `number` | No | Page number, starting at 0. The API returns 100 notifications per page. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `notifications` | `object[]` | Yes | — |
| `total` | `number \| null` | No | Notifications across all pages. |
| `page` | `number \| null` | No | This page, starting at 0. |
| `limit` | `number \| null` | No | — |
| `hasMore` | `boolean \| null` | No | True when another page exists. |

> [accordion] notifications full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   content?: string | null,
>   link?: string | null,
>   createdAt?: string | null
> }[]
> ```

***

## Posts

### changeStatus

`posts.changeStatus`

Move a post between draft and scheduled. Scheduling queues it to publish at its stored date to every channel it targets

**Risk:** `destructive`

```ts theme={null}
await corsair.postiz.api.posts.changeStatus({ id: 'post-123', status: 'draft' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The post id to move. |
| `status` | `draft \| schedule` | Yes | `draft` pulls the post back to a draft, and `schedule` returns it to the queue. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string \| null` | No | — |
| `state` | `string \| null` | No | The new state, `DRAFT` or `QUEUE`. |

***

### create

`posts.create`

Create a post as a draft, scheduled, or published immediately. A schedule or an immediate post goes out to every listed channel and cannot be recalled by this plugin once published

**Risk:** `destructive`

```ts theme={null}
await corsair.postiz.api.posts.create({ type: 'schedule', date: '2024-12-14T10:00:00.000Z', shortLink: false, tags: [], posts: [{ integration: { id: 'cm4ean69r0003w8w1cdomox9n' }, value: [{ content: 'Hello from the Postiz API!' }], settings: { __type: 'x', who_can_reply_post: 'everyone' } }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `draft \| schedule \| now` | Yes | `draft` saves without publishing, `schedule` queues for `date`, and `now` publishes as soon as Postiz takes it. |
| `date` | `string` | Yes | When to publish, as an ISO 8601 UTC timestamp. |
| `shortLink` | `boolean` | Yes | Whether Postiz shortens the links in the post. |
| `tags` | `object[]` | Yes | Tags to attach to the post. |
| `posts` | `object[]` | No | The per-integration posts. Required unless `type` is `draft`. |
| `inter` | `number` | No | Minutes between the parts of a thread. |

> [accordion] tags full type
>
> ```ts theme={null}
> {
>   value: string,
>   label: string
> }[]
> ```

> [accordion] posts full type
>
> ```ts theme={null}
> {
>   integration: {
>     id: string
>   },
>   value: {
>     content: string,
>     image?: {
>       id: string,
>       path: string,
>       thumbnailTimestamp?: number
>     }[],
>     id?: string
>   }[],
>   group?: string,
>   settings?: {
>     __type?: string | null
>   }
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `posts` | `object[]` | Yes | — |

> [accordion] posts full type
>
> ```ts theme={null}
> {
>   postId?: string | null,
>   integration?: string | null
> }[]
> ```

***

### delete

`posts.delete`

Delete a post, which also deletes every post in its group. A published post stays live on the platform

**Risk:** `destructive`

```ts theme={null}
await corsair.postiz.api.posts.delete({ id: 'post-123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The post id. Deleting one removes every post in its group. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The id that was deleted. |

***

### list

`posts.list`

List posts in a date window with their state, release URL and any platform error

**Risk:** `read`

```ts theme={null}
await corsair.postiz.api.posts.list({ startDate: '2024-12-01T00:00:00.000Z', endDate: '2024-12-31T23:59:59.000Z' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `startDate` | `string` | Yes | Inclusive start of the window, as an ISO 8601 timestamp. |
| `endDate` | `string` | Yes | Inclusive end of the window, as an ISO 8601 timestamp. |
| `customer` | `string` | No | Only posts for this customer (group) id. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `posts` | `object[]` | Yes | — |

> [accordion] posts full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   content?: string | null,
>   settings?: {
>     __type?: string | null
>   } | null,
>   publishDate?: string | null,
>   releaseURL?: string | null,
>   state?: string | null,
>   error?: string | null,
>   integration?: {
>     id?: string | null,
>     providerIdentifier?: string | null,
>     name?: string | null,
>     picture?: string | null
>   } | null
> }[]
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.