### Install @outstand-so/ui

Source: https://www.outstand.so/docs/sdk/ui

Installation commands for various package managers.

```bash
npm install @outstand-so/ui
```

```bash
yarn add @outstand-so/ui
```

```bash
pnpm add @outstand-so/ui
```

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

### Install the Outstand Plugin

Source: https://www.outstand.so/docs/claude-code

Commands to register the marketplace and install the plugin within a Claude Code session.

```bash
/plugin marketplace add Outstand-so/claude-code-marketplace
/plugin install outstand@outstand
```

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

### Install mcp-remote

Source: https://www.outstand.so/docs/mcp/setup

Install the required bridge utility for Claude Desktop and other editors to support streamable HTTP transport.

```bash
npm install -g mcp-remote
```

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

### Import Job Status Response Examples

Source: https://www.outstand.so/docs/get-import-job-status

Example JSON responses for successful and failed import job status requests.

```JSON
{
  "success": true,
  "data": {
    "id": "string",
    "orgId": "string",
    "socialAccountId": "string",
    "status": "queued",
    "since": "string",
    "until": "string",
    "limit": 0,
    "imported": 0,
    "skipped": 0,
    "failed": 0,
    "error": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "completedAt": "string"
  }
}
```

```JSON
{
  "success": false,
  "error": "Social account not found"
}
```

```JSON
{
  "success": false,
  "error": "Internal server error",
  "message": "Database connection failed"
}
```

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

### Import posts response examples

Source: https://www.outstand.so/docs/import-posts-from-a-social-account

JSON structures for successful import initiation and various error scenarios.

```json
{
  "success": true,
  "data": {
    "id": "string",
    "orgId": "string",
    "socialAccountId": "string",
    "status": "queued",
    "since": "string",
    "until": "string",
    "limit": 0,
    "imported": 0,
    "skipped": 0,
    "failed": 0,
    "error": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "completedAt": "string"
  }
}
```

```json
{
  "success": false,
  "error": "Session expired or invalid"
}
```

```json
{
  "success": false,
  "error": "Social account not found"
}
```

```json
{
  "success": false,
  "error": "Internal server error",
  "message": "Database connection failed"
}
```

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

### Perform Authenticated Request

Source: https://www.outstand.so/docs/authentication

Example of a successful GET request to the social-accounts endpoint.

```bash
curl -X GET https://api.outstand.so/v1/social-accounts \
  -H "Authorization: Bearer sk_live_abc123def456"
```

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

### Start the Outstand CLI

Source: https://www.outstand.so/docs/claude-code

Initializes the Outstand CLI to detect the project environment and route to the appropriate workflow.

```text
/outstand:start
```

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

### Create a Post Request

Source: https://www.outstand.so/docs/create-a-post

Example of a POST request to the /v1/posts endpoint using JavaScript fetch.

```javascript
const body = JSON.stringify({
  "accounts": [
    "x",
    "linkedin",
    "mycompany"
  ]
})

fetch("https://api.outstand.so/v1/posts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "b1f6c3f4-8f0e-4a5b-9c2d-7e1a0b3c4d5e"
  },
  body
})
```

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

### Fetch Account Metrics Request

Source: https://www.outstand.so/docs/get-account-metrics

Example request to retrieve metrics for a specific social account using the GET method.

```javascript
fetch("https://api.outstand.so/v1/social-accounts/string/metrics?since=1704067200&until=1706745600", {
  method: "GET"
})
```

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

### API Response Examples

Source: https://www.outstand.so/docs/confirm-upload

JSON response structures for successful and error scenarios.

```json
{
  "success": true,
  "data": {
    "id": "9dyJS",
    "filename": "product-image.jpg",
    "url": "https://media.outstand.so/org_abc123/550e8400-e29b-41d4-a716-446655440000/product-image.jpg",
    "content_type": "image/jpeg",
    "size": 1024000,
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "expires_at": "2025-03-16T10:30:00Z"
  }
}
```

```json
{
  "success": false,
  "error": "Invalid request",
  "details": {
    "filename": {
      "_errors": [
        "Required"
      ]
    }
  }
}
```

```json
{
  "success": false,
  "error": "Internal server error",
  "message": "Failed to generate upload URL"
}
```

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

### Fetch paginated posts

Source: https://www.outstand.so/docs/list-posts

Example request to retrieve posts using various query filters.

```JavaScript
fetch("https://api.outstand.so/v1/posts?social_account_id=9dyJS&tenant_id=tenant_123&tenantId=tenant_123&created_after=2025-01-01T00%3A00%3A00Z&created_before=2025-12-31T23%3A59%3A59Z&scheduled_after=2025-01-01T00%3A00%3A00Z&scheduled_before=2025-12-31T23%3A59%3A59Z&limit=50&offset=0", {
  method: "GET"
})
```

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

### Create a YouTube Short via API

Source: https://www.outstand.so/docs/configurations/youtube

Example request for creating a YouTube Short by setting the 'isShort' flag to true.

```bash
curl -X POST https://api.outstand.so/v1/posts/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containers": [
      {
        "content": "Check out this amazing tutorial!",
        "media": [
          {
            "url": "https://example.com/video.mp4",
            "filename": "video.mp4"
          }
        ]
      }
    ],
    "accounts": ["youtube"],
    "youtube": {
      "isShort": true,
      "privacyStatus": "public",
      "tags": ["tutorial", "shorts"]
    }
  }'
```

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

### Handle API Responses

Source: https://www.outstand.so/docs/authentication

Examples of successful and error response bodies.

```json
{
  "success": true,
  "data": [
    {
      "id": "acc_123",
      "network": "x",
      "username": "@mycompany"
    }
  ]
}
```

```json
{
  "success": false,
  "error": "Invalid or missing API key"
}
```

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

### GET https://app.outstand.so/api/socials/pinterest/{orgId}

Source: https://www.outstand.so/docs/configurations/pinterest

Initiates the OAuth flow to connect a Pinterest account.

```APIDOC
## GET https://app.outstand.so/api/socials/pinterest/{orgId}

### Description
Directs users to the OAuth initiation endpoint to connect their Pinterest account to the specified organization.

### Method
GET

### Endpoint
https://app.outstand.so/api/socials/pinterest/{orgId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier

#### Query Parameters
- **redirect_uri** (string) - Optional - Custom redirect URI after OAuth completes
- **tenant_id** (string) - Optional - Tenant identifier for multi-tenant applications
```

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

### Successful response example

Source: https://www.outstand.so/docs/get-pending-connection-details

The response body returned when the session token is valid and connection details are retrieved.

```json
{
  "success": true,
  "data": {
    "network": "linkedin",
    "expiresAt": 1734567890000,
    "availablePages": [
      {
        "id": "abc123",
        "type": "organization",
        "name": "Acme Inc",
        "username": "acme-inc",
        "profilePictureUrl": "https://example.com/profile.jpg"
      }
    ]
  }
}
```

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

### Media API response structures

Source: https://www.outstand.so/docs/list-media-files

Example JSON structures for successful and failed API responses.

```json
{
  "success": true,
  "data": [
    {
      "id": "9dyJS",
      "filename": "product-image.jpg",
      "url": "https://media.outstand.so/org_abc123/550e8400-e29b-41d4-a716-446655440000/product-image.jpg",
      "content_type": "image/jpeg",
      "size": 1024000,
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "expires_at": "2025-03-16T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 10
  }
}
```

```json
{
  "success": false,
  "error": "Internal server error",
  "message": "Failed to generate upload URL"
}
```

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

### Connect a Social Network via API

Source: https://www.outstand.so/docs/connect-a-new-social-network

Example request to register a new social network configuration using the POST /v1/social-networks endpoint.

```JavaScript
const body = JSON.stringify({  "network": "x",  "client_key": "abc123xyz789",  "client_secret": "secret_abc123xyz789_do_not_share"})fetch("https://api.outstand.so/v1/social-networks", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})
```

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

### Verifying Webhook Signatures

Source: https://www.outstand.so/docs/webhooks

This section provides examples for verifying the X-Outstand-Signature header using Node.js and Python to ensure the webhook request is authentic.

```APIDOC
## Verifying Webhook Signatures

### Description
To ensure that a webhook request originated from Outstand and has not been tampered with, you should verify the `X-Outstand-Signature` header. The signature is an HMAC-SHA256 hash of the raw request body, prefixed with 'sha256=', generated using your configured signing secret.

### Implementation Details
- **Algorithm**: HMAC-SHA256
- **Header**: `X-Outstand-Signature`
- **Verification**: Compute the HMAC-SHA256 hash of the raw request body using your secret and compare it to the provided signature using a timing-safe comparison function.

### Node.js Example
```javascript
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}
```

### Python Example
```python
import hmac
import hashlib

def verify_signature(payload: str, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)
```
```

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

### Post details response schema

Source: https://www.outstand.so/docs/get-post-details

Example of a successful 200 OK response containing the full post object structure.

```json
{
  "success": true,
  "post": {
    "id": "9dyJS",
    "orgId": "abc123",
    "publishedAt": "2019-08-24T14:15:22Z",
    "scheduledAt": "2019-08-24T14:15:22Z",
    "isDraft": true,
    "createdAt": "2019-08-24T14:15:22Z",
    "socialAccounts": [
      {
        "id": "9dyJS",
        "nickname": "string",
        "network": "string",
        "username": "string",
        "status": "published",
        "error": null,
        "platformPostId": "123456789",
        "platformPostUrl": "https://www.instagram.com/p/DAbCdEfGhIj/",
        "publishedAt": "2025-01-15T10:30:00Z"
      }
    ],
    "containers": [
      {
        "id": "8xKmL",
        "content": "string",
        "media": [
          {
            "url": "string",
            "filename": "string"
          }
        ],
        "publishResults": [
          {
            "accountId": "9dyJS",
            "status": "published",
            "platformCommentId": "urn:li:comment:(urn:li:share:123,456)",
            "error": null,
            "publishedAt": "2019-08-24T14:15:22Z"
          }
        ]
      }
    ]
  }
}
```

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

### Confirm Media Upload Request

Source: https://www.outstand.so/docs/confirm-upload

Example request to the confirm endpoint using the Fetch API.

```javascript
const body = JSON.stringify({})fetch("https://api.outstand.so/v1/media/string/confirm", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})
```

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

### Pinterest Boards Response

Source: https://www.outstand.so/docs/configurations/pinterest

Example JSON response containing board details such as ID, name, and privacy status.

```json
{
  "success": true,
  "data": [
    {
      "id": "123456789",
      "name": "Summer Collection",
      "description": "Our summer products",
      "pin_count": 42,
      "privacy": "PUBLIC"
    }
  ]
}
```

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

### Retrieve Post Status via API

Source: https://www.outstand.so/docs/post-lifecycle

Example response from the GET /v1/posts/{id} endpoint showing status, error details, and platform-specific information for social accounts.

```json
{
  "success": true,
  "post": {
    "id": "9dyJS",
    "publishedAt": "2025-01-15T10:30:00Z",
    "socialAccounts": [
      {
        "id": "abc123",
        "network": "facebook",
        "username": "MyPage",
        "status": "failed",
        "error": "Failed to upload Facebook photo from buffer: 400 - (#100) Invalid image",
        "platformPostId": null,
        "publishedAt": null
      },
      {
        "id": "def456",
        "network": "x",
        "username": "@myaccount",
        "status": "published",
        "error": null,
        "platformPostId": "1234567890123456789",
        "publishedAt": "2025-01-15T10:30:02Z"
      }
    ]
  }
}
```

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

### Implementing Complete Post Creation Flow

Source: https://www.outstand.so/docs/sdk/ui

Use the OutstandProvider, AccountsList, and CreatePostForm components to quickly set up a standard post creation interface.

```typescript
import {
	OutstandProvider,
	CreatePostForm,
	AccountsList
} from '@outstand-so/ui';

function PostManager() {
	return (
		<OutstandProvider apiKey="your-api-key">
			<div>
				<h2>Connected Accounts</h2>
				<AccountsList apiKey="your-api-key" />
				
				<h2>Create Post</h2>
				<CreatePostForm
					apiKey="your-api-key"
					enableScheduling={true}
					onPostCreated={(post) => {
						alert(`Post created: ${post.id}`);
					}}
				/>
			</div>
		</OutstandProvider>
	);
}
```

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

### Register Local Marketplace

Source: https://www.outstand.so/docs/claude-code

Command to register a local directory as a marketplace for plugin development.

```bash
/plugin marketplace add ./
```

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

### Upload and Confirm Media

Source: https://www.outstand.so/docs

Upload the raw file to the presigned URL and confirm the upload to activate the media.

```bash
# Step 2 - PUT the raw file bytes to the returned upload_url
curl -X PUT "PASTE_UPLOAD_URL_HERE" \
  -H "Content-Type: image/jpeg" \
  --data-binary @launch.jpg

# Step 3 - confirm the upload to activate it
curl -X POST https://api.outstand.so/v1/media/med_abc/confirm \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "size": 82451 }'
```

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

### get_social_account

Source: https://www.outstand.so/docs/mcp/tools

Get details of a specific connected account.

```APIDOC
## get_social_account

### Description
Get details of a specific connected account.

### Parameters
#### Path Parameters
- **social_account_id** (string) - Required - The account ID
```

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

### POST /v1/posts/

Source: https://www.outstand.so/docs/configurations/youtube

Creates a new post with YouTube-specific configuration options.

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

### Description
Creates a new post on the specified accounts. When including 'youtube' in the accounts list, you can provide a 'youtube' object to configure video-specific settings.

### Method
POST

### Endpoint
https://api.outstand.so/v1/posts/

### Parameters
#### Request Body
- **accounts** (array) - Required - List of account identifiers, including "youtube".
- **youtube** (object) - Optional - YouTube-specific configuration:
  - **isShort** (boolean) - Optional - Set to true to mark the video as a YouTube Short.
  - **categoryId** (string) - Optional - YouTube category ID.
  - **privacyStatus** (string) - Optional - One of "public", "private", or "unlisted".
  - **madeForKids** (boolean) - Optional - Whether the video is made for kids.
  - **tags** (array of strings) - Optional - Tags to add to the video.
  - **title** (string) - Optional - Custom title for the video.

### Request Example
{
  "accounts": ["youtube"],
  "youtube": {
    "isShort": true,
    "privacyStatus": "public",
    "tags": ["tutorial", "shorts"]
  }
}
```

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

### GET /v1/social-accounts

Source: https://www.outstand.so/docs

Retrieve a list of all connected social accounts.

```APIDOC
## GET /v1/social-accounts

### Description
Retrieves a list of all social accounts currently connected to the organization.

### Method
GET

### Endpoint
https://api.outstand.so/v1/social-accounts
```

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

### Adaptor Selection Logic

Source: https://www.outstand.so/docs/architecture

Conceptual pseudocode for selecting the appropriate platform adaptor based on the account network.

```pseudocode
adaptor      = selectAdaptor(account.network)
platformPostId = adaptor.publish(normalizedPost, account)
```

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

### get_account_metrics

Source: https://www.outstand.so/docs/mcp/tools

Get follower count and engagement metrics over a date range.

```APIDOC
## get_account_metrics

### Description
Get follower count and engagement metrics over a date range.

### Parameters
#### Query Parameters
- **social_account_id** (string) - Required - The account ID
- **start_date** (string) - Optional - Start date (ISO 8601)
- **end_date** (string) - Optional - End date (ISO 8601)
```

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

### Configure OutstandProvider

Source: https://www.outstand.so/docs/sdk/ui

Wrap the application or relevant components with the provider to supply the API key and base URL.

```jsx
import { OutstandProvider } from '@outstand-so/ui';

function App() {
	return (
		<OutstandProvider apiKey="your-api-key" baseUrl="https://api.outstand.so">
			{/* Your app components */}
		</OutstandProvider>
	);
}
```

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

### Response payloads

Source: https://www.outstand.so/docs/list-posts

Examples of successful and error response bodies returned by the API.

```JSON
{
  "success": true,
  "posts": [
    {
      "id": "9dyJS",
      "orgId": "abc123",
      "publishedAt": "2019-08-24T14:15:22Z",
      "scheduledAt": "2019-08-24T14:15:22Z",
      "isDraft": true,
      "createdAt": "2019-08-24T14:15:22Z",
      "socialAccounts": [
        {
          "id": "9dyJS",
          "nickname": "string",
          "network": "string",
          "username": "string",
          "status": "published",
          "error": null,
          "platformPostId": "123456789",
          "platformPostUrl": "https://www.instagram.com/p/DAbCdEfGhIj/",
          "publishedAt": "2025-01-15T10:30:00Z"
        }
      ],
      "containers": [
        {
          "id": "8xKmL",
          "content": "string",
          "media": [
            {
              "url": "string",
              "filename": "string"
            }
          ]
        }
      ]
    }
  ],
  "data": [
    {
      "id": "9dyJS",
      "orgId": "abc123",
      "publishedAt": "2019-08-24T14:15:22Z",
      "scheduledAt": "2019-08-24T14:15:22Z",
      "isDraft": true,
      "createdAt": "2019-08-24T14:15:22Z",
      "socialAccounts": [
        {
          "id": "9dyJS",
          "nickname": "string",
          "network": "string",
          "username": "string",
          "status": "published",
          "error": null,
          "platformPostId": "123456789",
          "platformPostUrl": "https://www.instagram.com/p/DAbCdEfGhIj/",
          "publishedAt": "2025-01-15T10:30:00Z"
        }
      ],
      "containers": [
        {
          "id": "8xKmL",
          "content": "string",
          "media": [
            {
              "url": "string",
              "filename": "string"
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "limit": 0,
    "offset": 0,
    "total": 0,
    "count": 0
  }
}
```

```JSON
{
  "success": false,
  "error": "Invalid payload",
  "code": "idempotency_key_reuse",
  "details": {
    "content": {
      "_errors": [
        "Required"
      ]
    }
  }
}
```

```JSON
{
  "success": false,
  "error": "Internal server error",
  "code": "idempotency_recovery_failed",
  "message": "Database connection failed"
}
```

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

### API response examples

Source: https://www.outstand.so/docs/finalize-pending-connection

Representations of successful and error responses returned by the finalize endpoint.

```json
{
  "success": true,
  "connectedAccounts": [
    {
      "id": "9dyJS",
      "nickname": "johndoe",
      "username": "johndoe",
      "network": "linkedin",
      "accountType": "personal"
    }
  ]
}
```

```json
{
  "success": false,
  "error": "Session expired or invalid"
}
```

```json
{
  "success": false,
  "error": "Session expired or invalid"
}
```

```json
{
  "success": false,
  "error": "Internal server error",
  "message": "Database connection failed"
}
```

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

### Configure Claude Desktop MCP

Source: https://www.outstand.so/docs/mcp/setup

Add the Outstand server configuration to the Claude Desktop settings file.

```json
{
  "mcpServers": {
    "outstand": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.outstand.so/mcp",
        "--header",
        "Authorization: Bearer ost_your_key"
      ]
    }
  }
}
```

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

### useOutstandApi

Source: https://www.outstand.so/docs/sdk/ui

Get API client methods for making authenticated requests to the Outstand platform.

```APIDOC
## useOutstandApi(options)

### Description
Provides an API client instance for performing HTTP requests with automatic authentication.

### Parameters
- **apiKey** (string) - Required - API key for authentication

### Methods
- **get<T>(endpoint)** - Perform a GET request
- **post<T>(endpoint, body)** - Perform a POST request
- **patch<T>(endpoint, body)** - Perform a PATCH request
- **delete<T>(endpoint)** - Perform a DELETE request
- **request<T>(endpoint, options)** - Perform a custom request
```

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

### Create Reddit Posts

Source: https://www.outstand.so/docs/configurations/reddit

Submit text or link posts to Reddit by including the required subreddit and title fields in the configuration.

```bash
curl -X POST https://api.outstand.so/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "We built a unified social media API and here is what we learned along the way...",
    "accounts": ["reddit"],
    "reddit": {
      "subreddit": "programming",
      "title": "We built a unified social media API - lessons learned"
    }
  }'
```

```bash
curl -X POST https://api.outstand.so/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "",
    "accounts": ["reddit"],
    "reddit": {
      "subreddit": "webdev",
      "title": "Outstand - one API for 12 social platforms",
      "url": "https://www.outstand.so"
    }
  }'
```

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

### GET /v1/media/{id}

Source: https://www.outstand.so/docs/get-media-file

Retrieves the details of a specific media file by its unique identifier.

```APIDOC
## GET /v1/media/{id}

### Description
Get details of a specific media file by its ID, including the public URL, content type, file size, upload status, and expiration date.

### Method
GET

### Endpoint
/v1/media/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The encoded string identifier of the media file.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - The media file details.
  - **id** (string) - The media ID.
  - **filename** (string) - The name of the file.
  - **url** (string) - The public URL of the media.
  - **content_type** (string) - The MIME type of the file.
  - **size** (integer) - The file size in bytes.
  - **status** (string) - The upload status (e.g., "active").
  - **created_at** (string) - ISO timestamp of creation.
  - **expires_at** (string) - ISO timestamp of expiration.

#### Response Example
{
  "success": true,
  "data": {
    "id": "9dyJS",
    "filename": "product-image.jpg",
    "url": "https://media.outstand.so/org_abc123/550e8400-e29b-41d4-a716-446655440000/product-image.jpg",
    "content_type": "image/jpeg",
    "size": 1024000,
    "status": "active",
    "created_at": "2025-01-15T10:30:00Z",
    "expires_at": "2025-03-16T10:30:00Z"
  }
}
```

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

### Register X Credentials via API

Source: https://www.outstand.so/docs/configurations/x

Use this POST request to add your X Client ID and Client Secret to the Outstand platform programmatically.

```bash
curl -X POST https://api.outstand.so/v1/social-networks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "x",
    "client_key": "YOUR_CLIENT_ID_HERE",
    "client_secret": "YOUR_CLIENT_SECRET_HERE"
  }'
```

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

### Request Media Upload URL

Source: https://www.outstand.so/docs

Initiate the media upload process by requesting a presigned URL.

```bash
# Step 1 - request an upload URL
curl -X POST https://api.outstand.so/v1/media/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "launch.jpg", "content_type": "image/jpeg" }'
```

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

### GET /v1/media

Source: https://www.outstand.so/docs/list-media-files

Retrieves a paginated list of all active (confirmed) media files for the organization.

```APIDOC
## GET /v1/media

### Description
Get a paginated list of all active (confirmed) media files for your organization. Only non-expired files are returned.

### Method
GET

### Endpoint
/v1/media

### Parameters
#### Query Parameters
- **limit** (string) - Optional - Number of media files per page (1-100). Default: "50"
- **offset** (string) - Optional - Pagination offset. Default: "0"

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **data** (array) - List of media file objects
- **pagination** (object) - Pagination metadata including limit, offset, and count

#### Response Example
{
  "success": true,
  "data": [
    {
      "id": "9dyJS",
      "filename": "product-image.jpg",
      "url": "https://media.outstand.so/org_abc123/550e8400-e29b-41d4-a716-446655440000/product-image.jpg",
      "content_type": "image/jpeg",
      "size": 1024000,
      "status": "active",
      "created_at": "2025-01-15T10:30:00Z",
      "expires_at": "2025-03-16T10:30:00Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "count": 10
  }
}
```

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

### POST /v1/posts/

Source: https://www.outstand.so/docs/getting-started

Creates a new post and schedules it for a future time. The accounts array defines the target platforms, and containers allow for threaded posts.

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

### Description
Create a post with a future `scheduledAt` to enqueue it. The `accounts` array is required for fan-out, and `containers` define the post content and optional replies.

### Method
POST

### Endpoint
https://api.outstand.so/v1/posts/

### Request Body
- **containers** (array) - Required - List of content objects. The first is the post, subsequent are replies.
- **accounts** (array) - Required - List of target network identifiers (e.g., "x", "linkedin").
- **scheduledAt** (string) - Required - ISO 8601 timestamp for scheduling.

### Request Example
{
  "containers": [
    { "content": "Post content", "media": [] },
    { "content": "Reply content" }
  ],
  "accounts": ["x", "linkedin"],
  "scheduledAt": "2026-04-01T09:00:00Z"
}

### Response
#### Success Response (200)
- **post** (object) - The created post object including `id` and `scheduledAt`.
```

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

### GET /api/socials/reddit/{orgId}

Source: https://www.outstand.so/docs/configurations/reddit

Initiates the OAuth flow for a user to connect their Reddit account.

```APIDOC
## GET /api/socials/reddit/{orgId}

### Description
Directs users to the OAuth initiation endpoint to connect their Reddit account to the specified organization.

### Method
GET

### Endpoint
https://app.outstand.so/api/socials/reddit/{orgId}

### Parameters
#### Path Parameters
- **orgId** (string) - Required - The organization identifier

#### Query Parameters
- **redirect_uri** (string) - Optional - Custom redirect URI after OAuth completes
- **tenant_id** (string) - Optional - Tenant identifier for multi-tenant applications
```

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

### Create a Post

Source: https://www.outstand.so/docs

Publish content to multiple social platforms in a single API call.

```bash
curl -X POST https://api.outstand.so/v1/posts/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "containers": [
      {
        "content": "Our Q2 launch is live 🚀",
        "media": [
          { "url": "https://media.outstand.so/org_abc/med_abc.jpg", "filename": "launch.jpg" }
        ]
      }
    ],
    "accounts": ["x", "linkedin"]
  }'
```

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

### Initiate Pinterest OAuth

Source: https://www.outstand.so/docs/configurations/pinterest

Direct users to this endpoint to begin the Pinterest account connection flow.

```http
GET https://app.outstand.so/api/socials/pinterest/{orgId}
```

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

### Implement MediaGallery Component

Source: https://www.outstand.so/docs/sdk/ui

Renders a grid of media files. Allows for removal of items and configuration of grid columns.

```javascript
import { MediaGallery } from '@outstand-so/ui';

<MediaGallery
	media={mediaFiles}
	onRemove={(index) => {
		setMediaFiles(prev => prev.filter((_, i) => i !== index));
	}}
	columns={3}
/>
```

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

### GET /v1/social-accounts/{id}/imports

Source: https://www.outstand.so/docs/list-import-jobs-for-a-social-account

Retrieves a list of all import jobs for the specified social account.

```APIDOC
## GET /v1/social-accounts/{id}/imports

### Description
Returns all import jobs for the specified social account, ordered by most recent first.

### Method
GET

### Endpoint
/v1/social-accounts/{id}/imports

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the social account.

### Request Example
```javascript
fetch("https://api.outstand.so/v1/social-accounts/string/imports", {
  method: "GET"
})
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (array) - A list of import job objects.
- **count** (integer) - The total number of import jobs returned.

#### Response Example
```json
{
  "success": true,
  "data": [
    {
      "id": "string",
      "orgId": "string",
      "socialAccountId": "string",
      "status": "queued",
      "since": "string",
      "until": "string",
      "limit": 0,
      "imported": 0,
      "skipped": 0,
      "failed": 0,
      "error": "string",
      "createdAt": "string",
      "updatedAt": "string",
      "completedAt": "string"
    }
  ],
  "count": 0
}
```
```

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

### GET /v1/posts/{id}

Source: https://www.outstand.so/docs/get-post-details

Retrieves detailed information about a specific post using its unique identifier.

```APIDOC
## GET /v1/posts/{id}

### Description
Get detailed information about a specific post by its ID, including all containers (content segments), attached media files, scheduling status, and publishing state.

### Method
GET

### Endpoint
/v1/posts/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the post.

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **post** (object) - The post object containing details like id, orgId, publishedAt, scheduledAt, isDraft, createdAt, socialAccounts, and containers.

#### Response Example
{
  "success": true,
  "post": {
    "id": "9dyJS",
    "orgId": "abc123",
    "publishedAt": "2019-08-24T14:15:22Z",
    "scheduledAt": "2019-08-24T14:15:22Z",
    "isDraft": true,
    "createdAt": "2019-08-24T14:15:22Z",
    "socialAccounts": [
      {
        "id": "9dyJS",
        "nickname": "string",
        "network": "string",
        "username": "string",
        "status": "published",
        "error": null,
        "platformPostId": "123456789",
        "platformPostUrl": "https://www.instagram.com/p/DAbCdEfGhIj/",
        "publishedAt": "2025-01-15T10:30:00Z"
      }
    ],
    "containers": [
      {
        "id": "8xKmL",
        "content": "string",
        "media": [
          {
            "url": "string",
            "filename": "string"
          }
        ],
        "publishResults": [
          {
            "accountId": "9dyJS",
            "status": "published",
            "platformCommentId": "urn:li:comment:(urn:li:share:123,456)",
            "error": null,
            "publishedAt": "2019-08-24T14:15:22Z"
          }
        ]
      }
    ]
  }
}
```

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

### GET /v1/social-accounts/{id}/imports/{importId}

Source: https://www.outstand.so/docs/get-import-job-status

Retrieves the current status and progress of an import job.

```APIDOC
## GET /v1/social-accounts/{id}/imports/{importId}

### Description
Returns the current status and progress of an import job.

### Method
GET

### Endpoint
/v1/social-accounts/{id}/imports/{importId}

### Parameters
#### Path Parameters
- **id** (string) - Required
- **importId** (string) - Required

### Response
#### Success Response (200)
- **success** (boolean)
- **data** (object) - Contains job details including id, orgId, socialAccountId, status, since, until, limit, imported, skipped, failed, error, createdAt, updatedAt, and completedAt.

#### Response Example
{
  "success": true,
  "data": {
    "id": "string",
    "orgId": "string",
    "socialAccountId": "string",
    "status": "queued",
    "since": "string",
    "until": "string",
    "limit": 0,
    "imported": 0,
    "skipped": 0,
    "failed": 0,
    "error": "string",
    "createdAt": "string",
    "updatedAt": "string",
    "completedAt": "string"
  }
}
```

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

### Get authorization URL

Source: https://www.outstand.so/docs/backend-integration

Retrieve the authorization URL to redirect users for social account connection.

```curl
curl -X GET https://api.outstand.so/v1/social-networks/{socialNetworkId}/auth-url \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

### Building Custom Post Creation Interfaces

Source: https://www.outstand.so/docs/sdk/ui

Compose individual components like PostComposer, NetworkSelector, and MediaUploader for granular control over the post creation process.

```typescript
import {
	OutstandProvider,
	PostComposer,
	NetworkSelector,
	MediaUploader,
	PostScheduler,
	NetworkConfigPanel,
	useAccounts
} from '@outstand-so/ui';

function CustomPostCreator() {
	const { accounts } = useAccounts({ apiKey: 'your-api-key' });
	const [content, setContent] = useState('');
	const [selectedIds, setSelectedIds] = useState<string[]>([]);
	const [media, setMedia] = useState<MediaFile[]>([]);
	const [scheduledAt, setScheduledAt] = useState<Date | null>(null);
	
	const handleSubmit = async () => {
		// Use usePosts hook to create post
		// ...
	};
	
	return (
		<div>
			<PostComposer
				value={content}
				onChange={setContent}
				selectedAccounts={accounts.filter(a => selectedIds.includes(a.id))}
			/>
			<NetworkSelector
				accounts={accounts}
				selectedIds={selectedIds}
				onChange={setSelectedIds}
			/>
			<MediaUploader
				apiKey="your-api-key"
				onUploadComplete={setMedia}
			/>
			<PostScheduler
				value={scheduledAt}
				onChange={setScheduledAt}
			/>
			<NetworkConfigPanel
				networks={[...new Set(accounts.filter(a => selectedIds.includes(a.id)).map(a => a.network))]}
				configs={{}}
				onChange={() => {}}
			/>
			<button onClick={handleSubmit}>Create Post</button>
		</div>
	);
}
```

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

### POST /v1/media/upload

Source: https://www.outstand.so/docs/get-upload-url

Request a presigned URL for uploading a media file directly to storage. The returned URL is valid for 1 hour.

```APIDOC
## POST /v1/media/upload

### Description
Request a presigned URL for uploading a media file directly to storage. The returned URL is valid for 1 hour.

### Method
POST

### Endpoint
https://api.outstand.so/v1/media/upload

### Request Body
- **filename** (string) - Required - The filename for the media file. Should include the file extension. Length: 1 <= length <= 255.
- **content_type** (string) - Optional - The MIME type of the file. If not provided, it will be inferred from the filename extension.

### Request Example
{
  "filename": "product-image.jpg"
}

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **data** (object) - Contains the upload details.
  - **id** (string) - The unique identifier for the media.
  - **upload_url** (string) - The presigned URL for the HTTP PUT upload.
  - **expires_in** (integer) - Expiration time in seconds.

#### Response Example
{
  "success": true,
  "data": {
    "id": "9dyJS",
    "upload_url": "https://media-bucket.r2.cloudflarestorage.com/...",
    "expires_in": 3600
  }
}
```

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

### Error response examples

Source: https://www.outstand.so/docs/get-post-analytics

Standard error responses for 400, 403, 404, and 500 status codes.

```JSON
{
  "success": false,
  "error": "Invalid payload",
  "code": "idempotency_key_reuse",
  "details": {
    "content": {
      "_errors": [
        "Required"
      ]
    }
  }
}
```

```JSON
{
  "success": false,
  "error": "Internal server error",
  "code": "idempotency_recovery_failed",
  "message": "Database connection failed"
}
```

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

### Full scheduler loop implementation

Source: https://www.outstand.so/docs

A complete workflow for discovering accounts, scheduling a post, and polling for the final publication status.

```typescript
const API_KEY = process.env.OUTSTAND_API_KEY!;
const BASE_URL = 'https://api.outstand.so';
const auth = { Authorization: `Bearer ${API_KEY}` };

// 1. Authenticate + discover accounts
const accountsRes = await fetch(`${BASE_URL}/v1/social-accounts`, { headers: auth });
const { data: accounts } = await accountsRes.json();

// 2. Schedule a post into your queue (a slot your own scheduler decided on)
const scheduledAt = new Date(Date.now() + 60 * 60 * 1000).toISOString(); // 1 hour out
const createRes = await fetch(`${BASE_URL}/v1/posts/`, {
  method: 'POST',
  headers: { ...auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    content: 'Scheduled with Outstand ⏰',
    accounts: accounts.map((a: any) => a.id),
    scheduledAt,
  }),
});
const { post } = await createRes.json();
console.log('Queued post:', post.id, 'for', post.scheduledAt);

// 3. Later: poll the outcome and interpret per-account status
const outcomeRes = await fetch(`${BASE_URL}/v1/posts/${post.id}`, { headers: auth });
const { post: result } = await outcomeRes.json();

for (const acc of result.socialAccounts) {
  if (acc.status === 'published') {
    console.log(`✅ ${acc.network}: ${acc.platformPostId}`);
  } else if (acc.status === 'failed') {
    console.error(`❌ ${acc.network}: ${acc.error}`);
  } else {
    console.log(`⏳ ${acc.network}: still ${acc.status}`);
  }
}
```

```python
import os
import requests
from datetime import datetime, timedelta, timezone

API_KEY = os.environ["OUTSTAND_API_KEY"]
BASE_URL = "https://api.outstand.so"
auth = {"Authorization": f"Bearer {API_KEY}"}

# 1. Authenticate + discover accounts
accounts = requests.get(f"{BASE_URL}/v1/social-accounts", headers=auth).json()["data"]

# 2. Schedule a post into your queue
scheduled_at = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat()
post = requests.post(
    f"{BASE_URL}/v1/posts/",
    headers={**auth, "Content-Type": "application/json"},
    json={
        "content": "Scheduled with Outstand ⏰",
        "accounts": [a["id"] for a in accounts],
        "scheduledAt": scheduled_at,
    },
).json()["post"]
print(f"Queued post {post['id']} for {post['scheduledAt']}")

# 3. Later: poll the outcome and interpret per-account status
result = requests.get(f"{BASE_URL}/v1/posts/{post['id']}", headers=auth).json()["post"]
for acc in result["socialAccounts"]:
    if acc["status"] == "published":
        print(f"✅ {acc['network']}: {acc['platformPostId']}")
    elif acc["status"] == "failed":
        print(f"❌ {acc['network']}: {acc['error']}")
    else:
        print(f"⏳ {acc['network']}: still {acc['status']}")
```