postqued-api

PostQued 社交媒体调度 API 集成。在对 PostQued 执行 API 调用以上传内容、发布到 TikTok（和其他平台）、管理平台帐户或查询发布状态时使用。触发涉及社交媒体发布、内容调度、TikTok 草稿发布或任何 PostQued API 操作的任务。

# PostQued API Skill

## Setup

Add your PostQued API key to your workspace `.env` file:

```
POSTQUED_API_KEY=pq_your_api_key_here
```

API keys are created in the PostQued dashboard at https://postqued.com/console. Keys start with `pq_` prefix.

## Authentication

All API requests require authentication via Bearer token:

```
Authorization: Bearer $POSTQUED_API_KEY
```

## Base URL

```
https://api.postqued.com
```

## API Documentation

OpenAPI spec: https://api.postqued.com/v1/docs/openapi.json

## Core Workflow: Upload and Publish Content

### Step 1: Upload Content

**For videos** (presigned URL upload):

```bash
# Start upload session
curl -X POST https://api.postqued.com/v1/content/upload \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "video.mp4",
    "contentType": "video/mp4",
    "fileSize": 52428800
  }'
# Response: { "contentId": "uuid", "upload": { "url": "presigned-url", "method": "PUT", "headers": {...} } }

# Upload file to presigned URL
curl -X PUT "PRESIGNED_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @video.mp4

# Confirm upload
curl -X POST https://api.postqued.com/v1/content/upload/complete \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentId": "uuid-from-step-1",
    "key": "content/user-id/content-id.mp4",
    "filename": "video.mp4",
    "contentType": "video/mp4",
    "size": 52428800,
    "width": 1920,
    "height": 1080,
    "durationMs": 30000
  }'
```

**For images** (direct upload):

```bash
curl -X POST https://api.postqued.com/v1/content/upload-image \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@image.jpg"
```

### Step 2: Get Platform Account ID

```bash
curl https://api.postqued.com/v1/platform-accounts?platform=tiktok \
  -H "Authorization: Bearer $POSTQUED_API_KEY"
# Response: { "accounts": [{ "id": "account-uuid", "username": "@user", ... }] }
```

### Step 3: Publish Content

**Important:** Always include a unique `Idempotency-Key` header (valid 24h).

```bash
curl -X POST https://api.postqued.com/v1/content/publish \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-uuid-per-request" \
  -d '{
    "contentIds": ["content-uuid"],
    "targets": [{
      "platform": "tiktok",
      "accountId": "account-uuid",
      "intent": "draft",
      "caption": "Check this out! #fyp",
      "dispatchAt": null,
      "options": {
        "privacyLevel": "SELF_ONLY",
        "disableDuet": false,
        "disableStitch": false,
        "disableComment": false
      }
    }]
  }'
# Response: { "publishId": "uuid", "status": "pending", "targets": [...] }
```

### Step 4: Check Publish Status

```bash
curl https://api.postqued.com/v1/content/publish/PUBLISH_ID \
  -H "Authorization: Bearer $POSTQUED_API_KEY"
```

## API Reference

See [references/api.md](references/api.md) for complete endpoint documentation.

## TikTok-Specific Options

| Option                | Type    | Description                                                                       |
| --------------------- | ------- | --------------------------------------------------------------------------------- |
| privacyLevel          | string  | `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` |
| disableDuet           | boolean | Disable duet                                                                      |
| disableStitch         | boolean | Disable stitch                                                                    |
| disableComment        | boolean | Disable comments                                                                  |
| videoCoverTimestampMs | integer | Cover frame timestamp (videos)                                                    |
| autoAddMusic          | boolean | Auto-add music (photos)                                                           |
| brandContentToggle    | boolean | Paid partnership disclosure                                                       |
| brandOrganicToggle    | boolean | Promotional content disclosure                                                    |

## Intent Values

- `draft` - Send to TikTok inbox as draft (user publishes manually)
- `publish` - Direct publish to user's TikTok profile

## Status Values

**Publish Request:** `pending` | `processing` | `completed` | `partial_failed` | `failed` | `canceled`

**Target:** `queued` | `scheduled` | `processing` | `sent` | `published` | `failed` | `canceled`

## Scheduling

Set `dispatchAt` to a future UTC ISO timestamp:

```json
{
  "dispatchAt": "2026-02-20T15:00:00Z"
}
```

Set to `null` for immediate dispatch.

## Rate Limits

| Operation | Limit  |
| --------- | ------ |
| Upload    | 20/min |
| Read      | 30/min |
| Publish   | 10/min |
| Delete    | 20/min |

## Error Handling

Errors return:

```json
{
  "error": "Message",
  "code": "ERROR_CODE"
}
```

Common codes: `MISSING_IDEMPOTENCY_KEY`, `IDEMPOTENCY_CONFLICT`, `SUBSCRIPTION_REQUIRED`

---

## 中文说明

# PostQued API 技能

## 设置

将你的 PostQued API 密钥添加到工作区的 `.env` 文件中：

```
POSTQUED_API_KEY=pq_your_api_key_here
```

API 密钥在 PostQued 控制台 https://postqued.com/console 创建。密钥以 `pq_` 前缀开头。

## 鉴权

所有 API 请求都需要通过 Bearer token 进行鉴权：

```
Authorization: Bearer $POSTQUED_API_KEY
```

## Base URL

```
https://api.postqued.com
```

## API 文档

OpenAPI 规范：https://api.postqued.com/v1/docs/openapi.json

## 核心工作流：上传并发布内容

### 第 1 步：上传内容

**视频**（预签名 URL 上传）：

```bash
# Start upload session
curl -X POST https://api.postqued.com/v1/content/upload \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "video.mp4",
    "contentType": "video/mp4",
    "fileSize": 52428800
  }'
# Response: { "contentId": "uuid", "upload": { "url": "presigned-url", "method": "PUT", "headers": {...} } }

# Upload file to presigned URL
curl -X PUT "PRESIGNED_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @video.mp4

# Confirm upload
curl -X POST https://api.postqued.com/v1/content/upload/complete \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentId": "uuid-from-step-1",
    "key": "content/user-id/content-id.mp4",
    "filename": "video.mp4",
    "contentType": "video/mp4",
    "size": 52428800,
    "width": 1920,
    "height": 1080,
    "durationMs": 30000
  }'
```

**图片**（直接上传）：

```bash
curl -X POST https://api.postqued.com/v1/content/upload-image \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@image.jpg"
```

### 第 2 步：获取平台账户 ID

```bash
curl https://api.postqued.com/v1/platform-accounts?platform=tiktok \
  -H "Authorization: Bearer $POSTQUED_API_KEY"
# Response: { "accounts": [{ "id": "account-uuid", "username": "@user", ... }] }
```

### 第 3 步：发布内容

**重要：** 始终包含一个唯一的 `Idempotency-Key` 头（有效期 24 小时）。

```bash
curl -X POST https://api.postqued.com/v1/content/publish \
  -H "Authorization: Bearer $POSTQUED_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-uuid-per-request" \
  -d '{
    "contentIds": ["content-uuid"],
    "targets": [{
      "platform": "tiktok",
      "accountId": "account-uuid",
      "intent": "draft",
      "caption": "Check this out! #fyp",
      "dispatchAt": null,
      "options": {
        "privacyLevel": "SELF_ONLY",
        "disableDuet": false,
        "disableStitch": false,
        "disableComment": false
      }
    }]
  }'
# Response: { "publishId": "uuid", "status": "pending", "targets": [...] }
```

### 第 4 步：检查发布状态

```bash
curl https://api.postqued.com/v1/content/publish/PUBLISH_ID \
  -H "Authorization: Bearer $POSTQUED_API_KEY"
```

## API 参考

完整的端点文档请参阅 [references/api.md](references/api.md)。

## TikTok 专属选项

| 选项                  | 类型    | 说明