### Temporal Post Workflow Setup

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Example setup for a Temporal worker that handles post publishing workflows. It includes activity definitions and task queue configuration.

```typescript
import { postWorkflowV102 } from '@gitroom/orchestrator/workflows/post-workflows/post.workflow.v1.0.2';

// The workflow is started via TemporalService — not called directly.
// Internally it:
// 1. Sleeps until publishDate
// 2. Calls postSocial() activity on the target platform
// 3. On RefreshToken error, refreshes OAuth token and retries (up to 5x)
// 4. Posts comment threads with optional delays between items
// 5. Fires outbound webhooks after publish
// 6. Processes plugs (e.g., auto-repost after N likes)
// 7. If intervalInDays is set, spawns a child workflow for the repeat

// Example Temporal worker setup (apps/orchestrator/src/main.ts pattern):
const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  activities: { ...postActivities, ...autopostActivities },
  taskQueue: 'main',
  connection,
});
await worker.run();
```

--------------------------------

### Install Postiz NodeJS SDK

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Install the Postiz NodeJS SDK using npm. This is the first step to integrate Postiz functionality into your Node.js application.

```bash
npm install @postiz/node
```

--------------------------------

### Initialize Postiz NodeJS SDK

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Initialize the Postiz SDK with your API key. Provide your self-hosted instance URL if applicable. This setup is required before calling any SDK methods.

```typescript
import Postiz from '@postiz/node';
const postiz = new Postiz('your api key', 'your self-hosted instance (optional)');
```

--------------------------------

### Run Development Server with npm, yarn, pnpm, or bun

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/frontend/README.md

Use these commands to start the development server for the Next.js project. Open http://localhost:3000 in your browser to view the application.

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev
```

--------------------------------

### Postiz App Development Commands

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Commands for starting the Postiz App development environment, applying database schema changes, and running all services.

```bash
# Start dev environment
pnpm dev:docker

# Apply database schema
pnpm prisma-db-push

# Start all services in parallel (backend, frontend, orchestrator, extension)
pnpm dev
```

--------------------------------

### Get Integration Settings

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieves platform-specific rules, maximum post length, and available AI tools for a connected channel using its ID.

```bash
curl https://api.postiz.com/public/v1/integration-settings/int_abc \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Get Integration Settings

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Returns platform-specific rules, maximum post length, and available AI tools for a connected channel.

```APIDOC
## GET /public/v1/integration-settings/:id

### Description
Returns platform-specific rules, maximum post length, and available AI tools for a connected channel.

### Method
GET

### Endpoint
/public/v1/integration-settings/:id

### Path Parameters
- **id** (string) - Required - The ID of the integration

### Response
#### Success Response (200)
- **output** (object)
  - **rules** (string) - Platform-specific rules (e.g., "X can have maximum 4 pictures, or maximum one video")
  - **maxLength** (integer) - Maximum allowed length for posts
  - **settings** (object) - Platform-specific settings
  - **tools** (array) - Available AI tools
    - **methodName** (string) - The method name for the tool
    - **label** (string) - The display label for the tool

#### Response Example
```json
{
  "output": {
    "rules": "X can have maximum 4 pictures, or maximum one video",
    "maxLength": 280,
    "settings": { ... },
    "tools": [ { "methodName": "repost", "label": "Repost" } ]
  }
}
```
```

--------------------------------

### Postiz Minimum Environment Variables

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Essential environment variables for a minimal self-hosted Postiz setup, including database, Redis, JWT secret, and URL configurations.

```bash
# .env — Minimum required configuration
DATABASE_URL="postgresql://postiz-user:postiz-password@localhost:5432/postiz-db"
REDIS_URL="redis://localhost:6379"
JWT_SECRET="a-long-random-secret-string-here"

# URL configuration — must match actual access URLs
FRONTEND_URL="https://postiz.example.com"
NEXT_PUBLIC_BACKEND_URL="https://postiz.example.com/api"
BACKEND_INTERNAL_URL="http://localhost:3000"

# File storage — use local or Cloudflare R2
STORAGE_PROVIDER="local"
UPLOAD_DIRECTORY="/var/postiz/uploads"
NEXT_PUBLIC_UPLOAD_STATIC_DIRECTORY="/uploads"

# --- OR use Cloudflare R2 ---
# STORAGE_PROVIDER="cloudflare"
# CLOUDFLARE_ACCOUNT_ID="..."
# CLOUDFLARE_ACCESS_KEY="..."
# CLOUDFLARE_SECRET_ACCESS_KEY="..."
```

--------------------------------

### Implement Custom Social Provider

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Example of implementing a custom social media provider by extending `SocialAbstract` and implementing the `SocialProvider` interface. Includes methods for authentication, token refresh, and posting.

```typescript
import { SocialAbstract } from '@gitroom/nestjs-libraries/integrations/social.abstract';
import {
  SocialProvider,
  AuthTokenDetails,
  PostDetails,
  PostResponse,
  GenerateAuthUrlResponse,
} from '@gitroom/nestjs-libraries/integrations/social/social.integrations.interface';

export class MyPlatformProvider extends SocialAbstract implements SocialProvider {
  identifier = 'myplatform';
  name = 'My Platform';
  isBetweenSteps = false;
  scopes = ['write:posts', 'read:account'];
  editor = 'normal' as const;

  maxLength() { return 500; }

  async generateAuthUrl(): Promise<GenerateAuthUrlResponse> {
    return {
      url: `https://myplatform.com/oauth/authorize?client_id=${process.env.MYPLATFORM_CLIENT_ID}&state=xyz`,
      codeVerifier: 'pkce_verifier',
      state: 'xyz',
    };
  }

  async authenticate(params: { code: string; codeVerifier: string }): Promise<AuthTokenDetails> {
    // Exchange code for token
    const tokenRes = await fetch('https://myplatform.com/oauth/token', {
      method: 'POST',
      body: JSON.stringify({ code: params.code, grant_type: 'authorization_code' }),
      headers: { 'Content-Type': 'application/json' },
    });
    const data = await tokenRes.json();
    return {
      id: data.user_id,
      name: data.display_name,
      username: data.username,
      accessToken: data.access_token,
      refreshToken: data.refresh_token,
      expiresIn: data.expires_in,
    };
  }

  async refreshToken(refreshToken: string): Promise<AuthTokenDetails> {
    const res = await fetch('https://myplatform.com/oauth/token', {
      method: 'POST',
      body: JSON.stringify({ refresh_token: refreshToken, grant_type: 'refresh_token' }),
      headers: { 'Content-Type': 'application/json' },
    });
    const data = await res.json();
    return { ...data, id: data.user_id, username: data.username, name: data.display_name, accessToken: data.access_token };
  }

  async post(id: string, accessToken: string, postDetails: PostDetails[]): Promise<PostResponse[]> {
    const [detail] = postDetails;
    // Use this.fetch() for built-in rate limit + refresh-token error handling
    const response = await this.fetch('https://myplatform.com/api/posts', {
      method: 'POST',
      headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: detail.message }),
    });
    const data = await response.json();
    return [{ id: detail.id, postId: data.id, releaseURL: `https://myplatform.com/post/${data.id}`, status: 'published' }];
  }
}
```

--------------------------------

### integrations()

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Get a list of connected channels. This method returns information about all channels integrated with your Postiz account.

```APIDOC
## integrations()

### Description
Get a list of connected channels. This method returns information about all channels integrated with your Postiz account.

### Method Signature
`integrations()`
```

--------------------------------

### Get Posts

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieves posts for the authenticated organization with optional query filters.

```APIDOC
## GET /public/v1/posts

### Description
Retrieves posts for the authenticated organization with optional query filters.

### Method
GET

### Endpoint
/public/v1/posts

### Query Parameters
- **display** (string) - Optional - Filter posts by display type (e.g., "week")
- **date** (string) - Optional - Filter posts by a specific date

### Response
#### Success Response (200)
- **posts** (array) - Array of post objects
  - **id** (string) - The ID of the post
  - **publishDate** (string) - The publish date of the post
  - **state** (string) - The state of the post
  - **integration** (object) - Integration details
    - **id** (string) - Integration ID
    - **providerIdentifier** (string) - Provider identifier
  - **content** (string) - The content of the post

#### Response Example
```json
{
  "posts": [
    {
      "id": "post_abc",
      "publishDate": "2025-08-01T10:00:00.000Z",
      "state": "PUBLISHED",
      "integration": { "id": "int_x", "providerIdentifier": "x" },
      "content": "Hello world!"
    }
  ]
}
```
```

--------------------------------

### Get Notifications

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Returns paginated in-app notifications for the organization. A 'page' query parameter can be used for pagination.

```bash
curl "https://api.postiz.com/public/v1/notifications?page=0" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Get Notifications

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Returns paginated in-app notifications for the organization.

```APIDOC
## GET /public/v1/notifications

### Description
Returns paginated in-app notifications for the organization.

### Method
GET

### Endpoint
/public/v1/notifications

### Query Parameters
- **page** (integer) - Optional - The page number for pagination (defaults to 0)

### Response
#### Success Response (200)
- **notifications** (array) - Array of notification objects
  - **id** (string) - Notification ID
  - **message** (string) - The notification message
  - **read** (boolean) - Whether the notification has been read
  - **createdAt** (string) - The timestamp when the notification was created
- **total** (integer) - The total number of notifications

#### Response Example
```json
{
  "notifications": [
    { "id": "notif_1", "message": "Your post has been published on X", "read": false, "createdAt": "..." }
  ],
  "total": 1
}
```
```

--------------------------------

### postList(filters: GetPostsDto)

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Get a list of posts. You can filter the posts using the provided DTO.

```APIDOC
## postList(filters: GetPostsDto)

### Description
Get a list of posts. You can filter the posts using the provided DTO.

### Method Signature
`postList(filters: GetPostsDto)`

### Parameters
- **filters** (GetPostsDto) - Required - An object containing filters to apply when retrieving the list of posts.
```

--------------------------------

### Docker Compose for Postiz App Development

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Docker Compose configuration for local development of the Postiz App. This setup includes the Postiz service, a PostgreSQL database, and Redis.

```yaml
# docker-compose.dev.yaml (excerpt — run with: pnpm dev:docker)
version: '3.8'
services:
  postiz:
    image: ghcr.io/gitroomhq/postiz-app:latest
    environment:
      DATABASE_URL: postgresql://postiz:postiz@db:5432/postiz
      REDIS_URL: redis://redis:6379
      JWT_SECRET: change-me-in-production
      FRONTEND_URL: http://localhost:4200
      NEXT_PUBLIC_BACKEND_URL: http://localhost:3000
      STORAGE_PROVIDER: local
      UPLOAD_DIRECTORY: /uploads
    volumes:
      - postiz_uploads:/uploads
    ports:
      - "4200:4200"
      - "3000:3000"
    depends_on:
      - db
      - redis

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postiz
      POSTGRES_PASSWORD: postiz
      POSTGRES_DB: postiz
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  postgres_data:
  postiz_uploads:
```

--------------------------------

### Create New Feature Branch

Source: https://github.com/gitroomhq/postiz-app/blob/main/CONTRIBUTING.md

Start a new branch for your feature or bug fix to keep changes isolated.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Get Analytics

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieves analytics time series for a connected channel or per-post analytics.

```APIDOC
## GET /analytics/:integration or GET /analytics/post/:postId

### Description
Returns analytics time series for a connected channel. `GET /analytics/post/:postId` returns per-post analytics.

### Method
GET

### Endpoint
/analytics/:integration or /analytics/post/:postId

### Parameters
#### Path Parameters
- **integration** (string) - Required - The identifier of the integration (for channel-level analytics).
- **postId** (string) - Required - The identifier of the post (for post-level analytics).
#### Query Parameters
- **date** (integer) - Required - A Unix timestamp representing the date for which to retrieve analytics.

### Request Example
```bash
# Channel-level analytics
curl "http://localhost:3000/analytics/int_abc?date=1722470400000" \
  -H "Cookie: auth=<jwt_token>"

# Post-level analytics
curl "http://localhost:3000/analytics/post/post_abc123?date=1722470400000" \
  -H "Cookie: auth=<jwt_token>"
```

### Response
#### Success Response (200)
- **label** (string) - The type of analytics data (e.g., "Likes").
- **data** (array) - An array of objects, each containing total count and date.
  - **total** (string) - The total count for the metric.
  - **date** (string) - The date for the metric.
- **percentageChange** (number) - The percentage change compared to the previous period.

#### Response Example
```json
[{ "label": "Likes", "data": [{ "total": "42", "date": "2025-08-01" }], "percentageChange": 5.2 }]
```
```

--------------------------------

### Valid SWR Hook Example

Source: https://github.com/gitroomhq/postiz-app/blob/main/CLAUDE.md

Demonstrates the correct way to define a custom SWR hook for data fetching, ensuring compliance with React Hooks rules. Each SWR call should be encapsulated within its own hook.

```typescript
const useCommunity = () => {
   return useSWR....
}
```

--------------------------------

### Get OAuth URL for Integration

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Generates an OAuth authorization URL for connecting a social channel programmatically.

```APIDOC
## GET /public/v1/social/:integration

### Description
Generates an OAuth authorization URL for connecting a social channel programmatically.

### Method
GET

### Endpoint
/public/v1/social/:integration

### Path Parameters
- **integration** (string) - Required - The identifier of the social integration (e.g., "linkedin")

### Response
#### Success Response (200)
- **url** (string) - The OAuth authorization URL

#### Response Example
```json
{ "url": "https://www.linkedin.com/oauth/v2/authorization?client_id=...&state=..." }
```
```

--------------------------------

### Get OAuth URL for Integration

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Generates an OAuth authorization URL for programmatically connecting a social channel. Specify the integration type (e.g., 'linkedin').

```bash
curl "https://api.postiz.com/public/v1/social/linkedin" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Get Analytics for Integration

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Fetches time-series analytics data, such as impressions and likes, for a connected channel. This is a public endpoint.

```APIDOC
## GET /public/v1/analytics/:integration

### Description
Returns time-series analytics data (impressions, likes, etc.) for a connected channel.

### Method
GET

### Endpoint
/public/v1/analytics/:integration

### Parameters
#### Path Parameters
- **integration** (string) - Required - The identifier of the integration.
#### Query Parameters
- **date** (integer) - Required - A Unix timestamp representing the date for which to retrieve analytics.

### Request Example
```bash
curl "https://api.postiz.com/public/v1/analytics/int_abc?date=1722470400000" \
  -H "Authorization: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **label** (string) - The type of analytics data (e.g., "Impressions").
- **data** (array) - An array of objects, each containing total count and date.
  - **total** (string) - The total count for the metric.
  - **date** (string) - The date for the metric.
- **percentageChange** (number) - The percentage change compared to the previous period.

#### Response Example
```json
[
  {
    "label": "Impressions",
    "data": [{ "total": "1200", "date": "2025-08-01" }],
    "percentageChange": 12.5
  }
]
```
```

--------------------------------

### Get Integration Analytics API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieve time-series analytics data for a connected channel using this public API. Requires an API key for authorization and a date parameter.

```bash
curl "https://api.postiz.com/public/v1/analytics/int_abc?date=1722470400000" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Invalid SWR Hook Example

Source: https://github.com/gitroomhq/postiz-app/blob/main/CLAUDE.md

Illustrates an incorrect pattern for defining SWR hooks where multiple fetches are grouped within a single hook, violating React Hooks rules. Avoid this structure to prevent linting errors.

```typescript
const useCommunity = () => {
  return {
    communities: () => useSWR<CommunitiesListResponse>("communities", getCommunities),
    providers: () => useSWR<ProvidersListResponse>("providers", getProviders),
  };
}
```

--------------------------------

### Get Analytics Time Series API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieve analytics time series data for a connected channel or a specific post using this internal API. Authentication is required.

```bash
# Channel-level analytics
curl "http://localhost:3000/analytics/int_abc?date=1722470400000" \
  -H "Cookie: auth=<jwt_token>"
```

```bash
# Post-level analytics
curl "http://localhost:3000/analytics/post/post_abc123?date=1722470400000" \
  -H "Cookie: auth=<jwt_token>"
```

--------------------------------

### Postiz SDK Initialization

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Instantiate the Postiz SDK client with your API key. Optionally, provide the URL for a self-hosted instance.

```APIDOC
## Initialization

### Description
Instantiate the Postiz SDK client with your API key. Optionally, provide the URL for a self-hosted instance.

### Usage
```typescript
import Postiz from '@postiz/node';
const postiz = new Postiz('your api key', 'your self-hosted instance (optional)');
```
```

--------------------------------

### Initialize Postiz Node.js Client

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Instantiate the Postiz client with your API key. Use the optional second argument for self-hosted instances.

```typescript
import Postiz from '@postiz/node';

// Hosted service
const postiz = new Postiz('YOUR_API_KEY');

// Self-hosted instance
const postizSelf = new Postiz('YOUR_API_KEY', 'https://your-postiz.example.com');
```

--------------------------------

### Upload from URL

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Fetches a remote image/video from a URL and saves it to Postiz storage. Requires Content-Type and Authorization headers.

```bash
curl -X POST https://api.postiz.com/public/v1/upload-from-url \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{ "url": "https://example.com/product-banner.jpg" }'
```

--------------------------------

### Clone Postiz Repository

Source: https://github.com/gitroomhq/postiz-app/blob/main/CONTRIBUTING.md

Clone your forked repository to your local machine to begin making changes.

```bash
git clone https://github.com/YOUR_USERNAME/postiz.git
```

--------------------------------

### List Integrations

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieves all social channels connected to the authenticated organization. Requires an Authorization header.

```bash
curl https://api.postiz.com/public/v1/integrations \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Create and Schedule a Post

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Use this endpoint to create and schedule a new post. Requires an Authorization header with the organization's API key.

```bash
curl -X POST https://api.postiz.com/public/v1/posts \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
    "type": "schedule",
    "date": "2025-08-15T14:00:00.000Z",
    "shortLink": false,
    "tags": [],
    "posts": [
      {
        "integration": { "id": "INTEGRATION_ID" },
        "value": [
          {
            "content": "Hello from the Postiz API! #automation",
            "image": []
          }
        ],
        "settings": { "__type": "x-provider" }
      }
    ]'
  }
```

--------------------------------

### upload(file: Buffer, extension: string)

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Upload a file to Postiz. This is useful for attaching media to your posts.

```APIDOC
## upload(file: Buffer, extension: string)

### Description
Upload a file to Postiz. This is useful for attaching media to your posts.

### Method Signature
`upload(file: Buffer, extension: string)`

### Parameters
- **file** (Buffer) - Required - The file content as a Buffer.
- **extension** (string) - Required - The file extension (e.g., 'png', 'jpg').
```

--------------------------------

### Upload from URL

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Fetches a remote image/video URL and saves it to Postiz storage.

```APIDOC
## POST /public/v1/upload-from-url

### Description
Fetches a remote image/video URL and saves it to Postiz storage.

### Method
POST

### Endpoint
/public/v1/upload-from-url

### Request Body
- **url** (string) - Required - The URL of the remote image or video

### Response
#### Success Response (200)
- **id** (string) - The ID of the uploaded media
- **path** (string) - The URL path to the uploaded media
- **name** (string) - The name of the uploaded file

#### Response Example
```json
{
  "id": "media_456",
  "path": "https://cdn.example.com/product-banner.jpg",
  "name": "upload.jpg"
}
```
```

--------------------------------

### Create a Post

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Creates and schedules a post. Requires an `Authorization` header with the organization's API key.

```APIDOC
## POST /public/v1/posts

### Description
Creates and schedules a post. Requires an `Authorization` header with the organization's API key.

### Method
POST

### Endpoint
/public/v1/posts

### Request Body
- **type** (string) - Required - Type of post operation (e.g., "schedule")
- **date** (string) - Required - The date and time to schedule the post
- **shortLink** (boolean) - Optional - Whether to use a short link
- **tags** (array) - Optional - Tags for the post
- **posts** (array) - Required - Array of post objects
  - **integration** (object) - Required - Integration details
    - **id** (string) - Required - Integration ID
  - **value** (array) - Required - Content of the post
    - **content** (string) - Required - The post text
    - **image** (array) - Optional - Array of images
  - **settings** (object) - Optional - Post settings
    - **__type** (string) - Required - Type of settings (e.g., "x-provider")

### Request Example
```json
{
  "type": "schedule",
  "date": "2025-08-15T14:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "INTEGRATION_ID" },
      "value": [
        {
          "content": "Hello from the Postiz API! #automation",
          "image": []
        }
      ],
      "settings": { "__type": "x-provider" }
    }
  ]
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the created post
- **group** (string) - The group ID for the post
- **publishDate** (string) - The scheduled publish date
- **state** (string) - The current state of the post (e.g., "QUEUE")

#### Response Example
```json
{
  "id": "post_abc123",
  "group": "grp_xyz",
  "publishDate": "2025-08-15T14:00:00.000Z",
  "state": "QUEUE"
}
```
```

--------------------------------

### Login User API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Authenticate a user and establish a session by setting the `auth` JWT cookie using this internal API.

```bash
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{ \
    "email": "user@example.com", \
    "password": "SecurePassword123!" \
  }'
```

--------------------------------

### Simple Media Upload API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Upload media files (images or videos) for posts using this internal API. It supports Cloudflare R2 or local storage and requires authentication.

```bash
curl -X POST http://localhost:3000/media/upload-simple \
  -H "Cookie: auth=<jwt_token>" \
  -F "file=@/path/to/video.mp4"
```

--------------------------------

### Upload a File

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Uploads a file (image or video) using multipart/form-data. Returns a media object with ID, path, and name.

```bash
curl -X POST https://api.postiz.com/public/v1/upload \
  -H "Authorization: YOUR_API_KEY" \
  -F "file=@/path/to/image.png"
```

--------------------------------

### Register New User API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Create a new user and organization with this internal API endpoint. It returns a JWT auth cookie. Email activation might be necessary if RESEND_API_KEY is configured.

```bash
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{ \
    "email": "user@example.com", \
    "password": "SecurePassword123!", \
    "company": "My Company", \
    "provider": "LOCAL" \
  }'
```

--------------------------------

### Register User and Organization

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Creates a new user and organization. Returns a JWT auth cookie. Email activation might be required.

```APIDOC
## POST /auth/register

### Description
Creates a new user and organization. Returns a JWT auth cookie. Email activation may be required if `RESEND_API_KEY` is configured.

### Method
POST

### Endpoint
/auth/register

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.
- **company** (string) - Required - The name of the company.
- **provider** (string) - Required - The authentication provider (e.g., "LOCAL").

### Request Example
```bash
curl -X POST http://localhost:3000/auth/register \
  -H "Content-Type: application/json" \
  -d '{ \
    "email": "user@example.com", \
    "password": "SecurePassword123!", \
    "company": "My Company", \
    "provider": "LOCAL" \
  }'
```

### Response
#### Success Response (200)
- **id** (string) - The organization ID.
- **activate** (boolean) - Indicates if email activation is required.

#### Response Example
```json
{ "id": "org_abc", ... } or { "activate": true }
```

### Headers
- **Set-Cookie**: `auth=<jwt_token>`
```

--------------------------------

### Retrieve Posts with Filters

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Fetches posts for the authenticated organization. Optional query filters like display week and date can be applied.

```bash
curl -X GET "https://api.postiz.com/public/v1/posts?display=week&date=2025-08-01" \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Push Changes to Fork

Source: https://github.com/gitroomhq/postiz-app/blob/main/CONTRIBUTING.md

Upload your local changes to your forked repository on GitHub.

```bash
git push -u origin feature/your-feature-name
```

--------------------------------

### post(posts: CreatePostDto)

Source: https://github.com/gitroomhq/postiz-app/blob/main/apps/sdk/README.md

Schedule a post to Postiz. This method allows you to create and schedule new posts.

```APIDOC
## post(posts: CreatePostDto)

### Description
Schedule a post to Postiz. This method allows you to create and schedule new posts.

### Method Signature
`post(posts: CreatePostDto)`

### Parameters
- **posts** (CreatePostDto) - Required - An object containing the details for the post to be created and scheduled.
```

--------------------------------

### Upload File with Postiz Node.js SDK

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Upload images or videos to Postiz storage. The returned media object can be used to attach files to posts. Requires Node.js 'fs' module for file reading.

```typescript
import Postiz from '@postiz/node';
import { readFileSync } from 'fs';

const postiz = new Postiz('YOUR_API_KEY');

const imageBuffer = readFileSync('./banner.png');
const media = await postiz.upload(imageBuffer, 'png');

console.log(media);
// { id: 'media_xyz', path: 'https://...', name: 'banner.png' }

// Use in a post:
await postiz.post({
  type: 'now',
  date: new Date().toISOString(),
  shortLink: false,
  tags: [],
  posts: [{
    integration: { id: 'INTEGRATION_ID' },
    value: [{
      content: 'Check out our new banner!',
      image: [{ id: media.id, path: media.path }],
    }],
    settings: { __type: 'linkedin-provider' },
  }],
});
```

--------------------------------

### Schedule a Post

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Submit one or more posts to be scheduled or published immediately across selected integrations using the `post` method. Supports various post types like 'schedule', 'draft', 'now', and 'update'.

```APIDOC
## SDK — Schedule a Post

`post(posts: CreatePostDto)` submits one or more posts to be scheduled or published immediately across selected integrations.

```typescript
import Postiz from '@postiz/node';

const postiz = new Postiz('YOUR_API_KEY');

const result = await postiz.post({
  type: 'schedule',          // 'draft' | 'schedule' | 'now' | 'update'
  date: '2025-08-01T10:00:00.000Z',
  shortLink: false,
  tags: [{ value: 'launch', label: 'Launch' }],
  posts: [
    {
      integration: { id: 'INTEGRATION_ID' },
      value: [
        {
          content: 'Excited to announce our new feature! 🚀 #buildinpublic',
          image: [],          // MediaDto[] for attached images/videos
        },
      ],
      settings: { __type: 'x-provider' },  // platform-specific settings discriminator
    },
  ],
});

console.log(result);
// { id: 'post_abc123', ... }
```
```

--------------------------------

### Schedule a Post with Postiz Node.js SDK

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Submit posts to be scheduled or published immediately. Supports various post types, scheduling dates, tags, and platform-specific settings.

```typescript
import Postiz from '@postiz/node';

const postiz = new Postiz('YOUR_API_KEY');

const result = await postiz.post({
  type: 'schedule',
  date: '2025-08-01T10:00:00.000Z',
  shortLink: false,
  tags: [{ value: 'launch', label: 'Launch' }],
  posts: [
    {
      integration: { id: 'INTEGRATION_ID' },
      value: [
        {
          content: 'Excited to announce our new feature! 🚀 #buildinpublic',
          image: [],
        },
      ],
      settings: { __type: 'x-provider' },
    },
  ],
});

console.log(result);
// { id: 'post_abc123', ... }
```

--------------------------------

### List Integrations

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Returns all social channels connected to the authenticated organization.

```APIDOC
## GET /public/v1/integrations

### Description
Returns all social channels connected to the authenticated organization.

### Method
GET

### Endpoint
/public/v1/integrations

### Response
#### Success Response (200)
- **integrations** (array) - Array of integration objects
  - **id** (string) - Integration ID
  - **name** (string) - Name of the social channel
  - **identifier** (string) - Provider identifier (e.g., "x", "linkedin")
  - **disabled** (boolean) - Whether the integration is disabled
  - **profile** (string) - Optional - Profile name for the integration

#### Response Example
```json
[
  { "id": "int_1", "name": "My Brand X", "identifier": "x", "disabled": false, "profile": "mybrand" },
  { "id": "int_2", "name": "Company LinkedIn", "identifier": "linkedin", "disabled": false }
]
```
```

--------------------------------

### Upload a File

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Upload an image or video to Postiz storage using the `upload` method. Returns a media object that can be attached to posts.

```APIDOC
## SDK — Upload a File

`upload(file: Buffer, extension: string)` uploads an image or video to Postiz storage and returns a media object suitable for attaching to posts.

```typescript
import Postiz from '@postiz/node';
import { readFileSync } from 'fs';

const postiz = new Postiz('YOUR_API_KEY');

const imageBuffer = readFileSync('./banner.png');
const media = await postiz.upload(imageBuffer, 'png');

console.log(media);
// { id: 'media_xyz', path: 'https://...', name: 'banner.png' }

// Use in a post:
await postiz.post({
  type: 'now',
  date: new Date().toISOString(),
  shortLink: false,
  tags: [],
  posts: [{
    integration: { id: 'INTEGRATION_ID' },
    value: [{
      content: 'Check out our new banner!',
      image: [{ id: media.id, path: media.path }],
    }],
    settings: { __type: 'linkedin-provider' },
  }],
});
```
```

--------------------------------

### List Connected Integrations with Postiz Node.js SDK

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieve a list of all social media channels connected to your Postiz organization. Provides details like account name, identifier, and profile handle.

```typescript
import Postiz from '@postiz/node';

const postiz = new Postiz('YOUR_API_KEY');

const channels = await postiz.integrations();
console.log(channels);
// [
//   {
//     id: 'int_abc',
//     name: 'My X Account',
//     identifier: 'x',
//     picture: 'https://...',
//     disabled: false,
//     profile: 'myhandle',
//     customer: null,
//   },
//   { id: 'int_def', identifier: 'linkedin', ... }
// ]
```

--------------------------------

### List Posts with Postiz Node.js SDK

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Retrieve a paginated list of posts, with options to filter by date range or state. Useful for managing existing scheduled or published content.

```typescript
import Postiz from '@postiz/node';

const postiz = new Postiz('YOUR_API_KEY');

const posts = await postiz.postList({
  // Optional filters (all are optional)
  display: 'week',
  date: '2025-08-01',
});

console.log(posts);
// { posts: [ { id, publishDate, state, content, ... }, ... ] }
```

--------------------------------

### Login User

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Authenticates a user and sets the `auth` JWT cookie.

```APIDOC
## POST /auth/login

### Description
Authenticates a user and sets the `auth` JWT cookie.

### Method
POST

### Endpoint
/auth/login

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```bash
curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{ \
    "email": "user@example.com", \
    "password": "SecurePassword123!" \
  }'
```

### Headers
- **Set-Cookie**: `auth=<jwt_token>`
```

--------------------------------

### Upload a File

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Uploads a file (image or video) as multipart/form-data and returns a media object.

```APIDOC
## POST /public/v1/upload

### Description
Uploads a file (image or video) as multipart/form-data and returns a media object.

### Method
POST

### Endpoint
/public/v1/upload

### Request Body
- **file** (file) - Required - The file to upload

### Response
#### Success Response (200)
- **id** (string) - The ID of the uploaded media
- **path** (string) - The URL path to the uploaded media
- **name** (string) - The name of the uploaded file

#### Response Example
```json
{
  "id": "media_123",
  "path": "https://cdn.example.com/image.png",
  "name": "image.png"
}
```
```

--------------------------------

### Upload Media File

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Uploads a media file (image or video) for use in posts. Supports Cloudflare R2 or local storage.

```APIDOC
## POST /media/upload-simple

### Description
Uploads a media file (image or video) for use in posts. Supports Cloudflare R2 or local storage.

### Method
POST

### Endpoint
/media/upload-simple

### Parameters
#### Form Data
- **file** (file) - Required - The media file to upload.

### Request Example
```bash
curl -X POST http://localhost:3000/media/upload-simple \
  -H "Cookie: auth=<jwt_token>" \
  -F "file=@/path/to/video.mp4"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the uploaded media.
- **path** (string) - The URL path to the uploaded media.
- **name** (string) - The original filename of the uploaded media.

#### Response Example
```json
{ "id": "media_789", "path": "https://cdn.example.com/video.mp4", "name": "video.mp4" }
```
```

--------------------------------

### Find Free Scheduling Slot API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Use this public API to retrieve the next available free scheduling slot for a specific integration. Requires an API key for authorization.

```bash
curl https://api.postiz.com/public/v1/find-slot/int_abc \
  -H "Authorization: YOUR_API_KEY"
```

--------------------------------

### Generate AI Image

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Generates an AI image from a text prompt using OpenAI and returns a base64-encoded PNG. Requires credits.

```APIDOC
## POST /media/generate-image

### Description
Generates an AI image from a text prompt using OpenAI and returns a base64-encoded PNG. Requires credits.

### Method
POST

### Endpoint
/media/generate-image

### Parameters
#### Request Body
- **prompt** (string) - Required - The text prompt to generate the image from.

### Request Example
```bash
curl -X POST http://localhost:3000/media/generate-image \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=<jwt_token>" \
  -d '{ "prompt": "A futuristic cityscape at sunset, digital art style" }'
```

### Response
#### Success Response (200)
- **output** (string) - A base64-encoded PNG image string.

#### Response Example
```json
{ "output": "data:image/png;base64,iVBORw0KGgo..." }
```
```

--------------------------------

### AI Image Generation API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Generate AI images from text prompts using OpenAI via this internal API. It requires available credits and returns a base64-encoded PNG. Authentication is required.

```bash
curl -X POST http://localhost:3000/media/generate-image \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=<jwt_token>" \
  -d '{ "prompt": "A futuristic cityscape at sunset, digital art style" }'
```

--------------------------------

### Postiz App Environment Variables

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Essential environment variables for configuring Postiz App, including cloud storage, email, AI features, social OAuth, Stripe billing, and rate limiting.

```env
# CLOUDFLARE_BUCKETNAME="postiz-media"
# CLOUDFLARE_BUCKET_URL="https://bucket.r2.cloudflarestorage.com/"

# Email (optional — if set, email activation is required for new users)
RESEND_API_KEY="re_xxxxxxxxxxxx"
EMAIL_FROM_ADDRESS="noreply@example.com"
EMAIL_FROM_NAME="Postiz"

# AI features
OPENAI_API_KEY="sk-..."

# Social platform OAuth credentials (add only the platforms you need)
X_API_KEY="..."
X_API_SECRET="..."
LINKEDIN_CLIENT_ID="..."
LINKEDIN_CLIENT_SECRET="..."
DISCORD_CLIENT_ID="..."
DISCORD_CLIENT_SECRET="..."
DISCORD_BOT_TOKEN_ID="..."

# Stripe billing (optional — for the managed/SaaS deployment)
STRIPE_PUBLISHABLE_KEY="pk_live_..."
STRIPE_SECRET_KEY="sk_live_..."

# Rate limiting
API_LIMIT=30   # Max public API requests per hour per organization
```

--------------------------------

### Manage Webhooks API

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Manage outbound webhooks for post publishing events using this internal API. Supports creation, retrieval, update, and deletion. Authentication is required.

```bash
# Create a webhook
curl -X POST http://localhost:3000/webhooks \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=<jwt_token>" \
  -d '{ \
    "url": "https://n8n.example.com/webhook/postiz", \
    "type": "POST_PUBLISHED" \
  }'
```

```bash
# Test-fire a webhook manually
curl -X POST "http://localhost:3000/webhooks/send?url=https://n8n.example.com/webhook/test" \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=<jwt_token>" \
  -d '{ "event": "test", "postId": "post_abc" }'
```

--------------------------------

### Manage Autopost Rules

Source: https://context7.com/gitroomhq/postiz-app/llms.txt

Configures and manages rules for automatically creating posts from RSS/Atom feeds.

```APIDOC
## Autopost Operations (POST)

### Description
Autopost watches an RSS/Atom feed and automatically creates posts from new items on a schedule. Supports creation and enabling/disabling.

### Method
POST

### Endpoint
/autopost or /autopost/:autopost_id/active

### Parameters
#### POST /autopost
##### Request Body
- **url** (string) - Required - The URL of the RSS/Atom feed.
- **integration** (object) - Required - Information about the integration.
  - **id** (string) - Required - The identifier of the integration.
- **active** (boolean) - Required - Whether the autopost rule is active.

#### POST /autopost/:autopost_id/active
##### Path Parameters
- **autopost_id** (string) - Required - The ID of the autopost rule to modify.
##### Request Body
- **active** (boolean) - Required - The new active status for the autopost rule.

### Request Example
```bash
# Create an autopost rule
curl -X POST http://localhost:3000/autopost \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=<jwt_token>" \
  -d '{ \
    "url": "https://myblog.com/rss.xml", \
    "integration": { "id": "int_linkedin" }, \
    "active": true \
  }'

# Enable/disable an autopost rule
curl -X POST http://localhost:3000/autopost/autopost_id/active \
  -H "Content-Type: application/json" \
  -H "Cookie: auth=<jwt_token>" \
  -d '{ "active": false }'
```
```