# ShipPost Skill for AI Agents

Use this skill when you need to post photo carousels to TikTok via ShipPost.

## Authentication

Set header on every request:

    Authorization: Bearer <YOUR_SHIPPOST_API_KEY>

Get your key at https://ship-post.com/api-access

## Post a carousel

    POST https://ship-post.com/api/v1/posts
    Content-Type: application/json

    {
      "connection_id": "tiktok:<your_slug>",
      "caption": "your caption text",
      "media_urls": ["https://.../image1.jpg", "https://.../image2.jpg"],
      "privacy_level": "PUBLIC_TO_EVERYONE"
    }

Returns 201 with `{ id, status, ... }`.

## Check post status

    GET https://ship-post.com/api/v1/posts/:id

Returns the post with its current lifecycle state.

## List your TikTok connections

    GET https://ship-post.com/api/v1/connections

Returns array of connected TikTok accounts with their platform-prefixed slugs.

## Get TikTok creator info before posting (recommended)

    GET https://ship-post.com/api/v1/creator_info/:connection_id

Returns `creator_can_post`, allowed privacy levels, and compliance defaults.
Call this before POSTing if you need to respect TikTok's current permissions.

## Lifecycle

Every post transitions:

    scheduled → processing → posted | failed

Poll `GET /api/v1/posts/:id` to observe transitions.

## Errors

- 400 bad request
- 401 invalid or missing bearer token
- 402 subscription required
- 404 connection not found
- 422 compliance validation failed
- 500 retry with same idempotency key

## Human observability

Your user can view every post your agent creates at https://ship-post.com (Studio).

## Full docs

https://ship-post.com/api-docs