# ShipPost — Agent Setup Context

ShipPost lets your AI agent authenticate, inspect connected TikTok accounts, and create TikTok photo posts once the user's Starter subscription is active.

Base URL: https://fellowships4you.com
MCP endpoint: https://fellowships4you.com/mcp
Docs: https://fellowships4you.com/docs

---

## 1. Add ShipPost to your MCP config

```json
{
  "mcpServers": {
    "shippost": {
      "url": "https://fellowships4you.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

---

## 2. Get an API key

1. Sign up at https://fellowships4you.com/accounts/sign_up
2. Connect TikTok via OAuth
3. Generate an API key at https://fellowships4you.com/api-access
4. Paste the key (starts with `spk_`) into the Bearer header above
5. Verify setup with `GET /api/v1/connections` before paying
6. Upgrade to Starter at https://fellowships4you.com/billing when ready to publish

---

## 3. Tools available to your agent

### listConnections

List the user's connected social accounts. Call this first to discover which
platforms and accounts are available.

**Parameters:**
- `platform` (optional): filter by platform. One of `tiktok`, `instagram`, `pinterest`.

**Returns:**
```json
{
  "connections": [
    {
      "id": 17,
      "platform": "tiktok",
      "slug": "tiktok:dxp-labs-ios",
      "display_name": "dxp_labs_iOS",
      "platform_user_id": "7348200000000",
      "token_active": true
    }
  ]
}
```

Use the `slug` (e.g. `tiktok:dxp-labs-ios`) as the `connection_id` in subsequent
calls. Slugs are stable across reconnects; numeric IDs are not.

---

### createPost

Create a TikTok photo post for a connected account.

**Required parameters:**
- `connection_id` (string): slug from `listConnections`, e.g. `"tiktok:dxp-labs-ios"`
- `content_type` (string): `"photo"`
- `caption` (string): post caption text

**TikTok-specific required:**
- `privacy_level` (string): one of `"PUBLIC_TO_EVERYONE"`, `"MUTUAL_FOLLOW_FRIENDS"`, `"FOLLOWER_OF_CREATOR"`, `"SELF_ONLY"`

**For photo posts:**
- `photo_urls` (array of strings): public URLs to image files (JPG/PNG). Must be publicly fetchable by TikTok's servers.

**Optional parameters:**
- `allow_comment` (boolean, default `true`)
- `allow_duet` (boolean, default `false`)
- `allow_stitch` (boolean, default `false`)
- `auto_add_music` (boolean, default `true`) — TikTok auto music for photo carousels
- `disclose_content` (boolean, default `false`) — required if sponsored
- `brand_organic` (boolean, default `false`) — "Your brand" disclosure
- `brand_content` (boolean, default `false`) — "Branded content" / paid partnership

**Example — photo carousel:**
```json
{
  "connection_id": "tiktok:dxp-labs-ios",
  "content_type": "photo",
  "caption": "Futuristic cities at sunset",
  "privacy_level": "PUBLIC_TO_EVERYONE",
  "photo_urls": [
    "https://example.com/img1.jpg",
    "https://example.com/img2.jpg",
    "https://example.com/img3.jpg"
  ]
}
```

**Returns:**
```json
{
  "id": 42,
  "status": "queued",
  "publish_id": null
}
```

The post is queued immediately and published in the background. Use `showPost`
with the returned `id` to poll status.

If the account is not subscribed, `createPost` returns a payment-required error
with a link to billing.

---

### showPost

Check the status of a post you created.

**Required parameters:**
- `id` (integer): post ID from the `createPost` response

**Returns:**
```json
{
  "id": 42,
  "status": "posted",
  "content_type": "photo",
  "caption": "Futuristic cities at sunset",
  "privacy_level": "PUBLIC_TO_EVERYONE",
  "platform_post_id": "7290000000000000000",
  "publish_id": "v_pub_file~v2.abc123",
  "last_error": null,
  "created_at": "2026-04-07T02:30:00Z",
  "posted_at": "2026-04-07T02:31:42Z"
}
```

**Status values:**
- `queued` — waiting for background worker
- `uploading` — being uploaded to the platform
- `posted` — successfully published
- `failed` — check `last_error` for details
- `cancelled` — user cancelled before publish

---

## 4. Typical agent workflow

```
User: "Post these 3 images to my TikTok with the caption 'AI art dump'"

Agent:
  1. Call listConnections → find tiktok:dxp-labs-ios
  2. Call createPost with:
       connection_id: "tiktok:dxp-labs-ios"
       content_type: "photo"
       caption: "AI art dump"
       privacy_level: "PUBLIC_TO_EVERYONE"
       photo_urls: ["https://...", "https://...", "https://..."]
  3. Receive { id: 42, status: "queued" }
  4. (optional) Call showPost with id 42 a minute later to confirm "posted"
```

---

## 5. Important constraints

- **Image URLs must be publicly accessible.** TikTok's servers fetch them directly; localhost and auth-protected URLs will fail.
- **TikTok requires `privacy_level`** for every post. Instagram and Pinterest don't.
- **Branded content cannot be `SELF_ONLY`.** If `brand_content: true`, privacy must be public or friends.
- **Connection slugs are stable; numeric IDs are not.** Always use `platform:slug` format (e.g. `tiktok:my-account`).
- **Photo carousels:** 1–35 images per post on TikTok.
- **Rate limits:** TikTok's API has per-day and per-minute limits; surface any `last_error` from `showPost` to the user.
- **Pre-payment behavior:** the API key works for auth, docs, MCP initialize, and `listConnections`; only `createPost` is billing-gated.

---

## 6. Troubleshooting

**"Connection not found"** — The slug you passed doesn't match any connected account. Call `listConnections` first.

**"privacy_level is required for TikTok"** — Add `privacy_level: "PUBLIC_TO_EVERYONE"` (or another valid value) to the request.

**"Subscription required to create TikTok posts."** — The key is valid, but publishing is locked until the user activates Starter at https://fellowships4you.com/billing.

**Post status is "failed"** — Check `last_error` field in the `showPost` response. Common causes: expired OAuth token (user must reconnect), image URL not fetchable, TikTok rate limit, or branded content + private mix.

**MCP `isError: true`** — The server returned a non-2xx status. The `content[0].text` field contains the error body.

---

## 7. Links

- Sign up: https://fellowships4you.com/accounts/sign_up
- API key management: https://fellowships4you.com/api-access
- This docs page: https://fellowships4you.com/docs
- Plain-text version (for curl): https://fellowships4you.com/docs.txt
- Billing: https://fellowships4you.com/billing