API Docs

Everything your agent needs to post to TikTok through ShipPost. One endpoint, one job, one lifecycle.

Authentication

All endpoints require a bearer token in the Authorization header:

Authorization: Bearer <your_api_key>

Get your key from the API Access page after signing in.

Create a post

POST /api/v1/posts

curl -X POST https://ship-post.com/api/v1/posts \
  -H "Authorization: Bearer $SHIPPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connection_id": "tiktok:weddingvisionai",
    "caption": "your caption",
    "media_urls": ["https://example.com/image1.jpg"],
    "privacy_level": "PUBLIC_TO_EVERYONE"
  }'

Response 201 Created:

{
  "id": 42,
  "status": "scheduled",
  "connection_id": "tiktok:weddingvisionai",
  "caption": "your caption",
  "created_at": "2026-04-07T12:00:00Z"
}

Get post status

GET /api/v1/posts/:id

curl https://ship-post.com/api/v1/posts/42 \
  -H "Authorization: Bearer $SHIPPOST_API_KEY"

List connections

GET /api/v1/connections — lists every TikTok account your team has connected.

curl https://ship-post.com/api/v1/connections \
  -H "Authorization: Bearer $SHIPPOST_API_KEY"

Creator info

GET /api/v1/creator_info/:connection_id — TikTok's creator metadata including creator_can_post, available privacy levels, and interaction defaults. Call this before posting if you need to respect the creator's current posting permissions.

Job lifecycle

Every post transitions through these states:

State	Meaning
`scheduled`	Post is queued for processing.
`processing`	We're uploading to TikTok now.
`posted`	TikTok accepted the post.
`failed`	Terminal failure. See `error` on the response.

Errors

HTTP	Meaning
`400`	Malformed request — check body and required fields.
`401`	Missing or invalid bearer token.
`402`	Subscription required (upgrade link returned in body).
`404`	Connection not found.
`422`	TikTok compliance validation failed (privacy level, branded content, etc.).
`500`	Server error — retry with the same idempotency key.

Agent integration

Download shippost-skill.md and drop it into your agent's skill directory.

Plain-text docs

Agents that prefer a raw text fetch can curl /docs.txt.