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):
# 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):
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
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).
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
curl https://api.postqued.com/v1/content/publish/PUBLISH_ID \
-H "Authorization: Bearer $POSTQUED_API_KEY"
API Reference
See 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:
{
"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:
{
"error": "Message",
"code": "ERROR_CODE"
}
Common codes: MISSING_IDEMPOTENCY_KEY, IDEMPOTENCY_CONFLICT, SUBSCRIPTION_REQUIRED
