Agent Docs

Everything your AI agent needs to post via ShipPost.

# 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:your-brand",
      "display_name": "dxp_labs_iOS",
      "platform_user_id": "7348200000000",
      "token_active": true
    }
  ]
}
```

Use the `slug` (e.g. `tiktok:your-brand`) 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:your-brand"`
- `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:your-brand",
  "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:your-brand
  2. Call createPost with:
       connection_id: "tiktok:your-brand"
       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. Managed automation: Products + Templates

Once your account has `FEATURE_AUTOMATION` enabled (paid tier), your agent can provision **Products** — recurring TikTok/IG/Pinterest workflows that run on a cron-style schedule and post automatically. A Product wraps a **content_type** (the workflow shape), a **prompt_library**, a schedule, and a connection.

### content_types

| `content_type` | What it does | `prompt_library` shape |
|---|---|---|
| `single_prompt_carousel` | One prompt → N AI images → carousel post | `["prompt", ...]` |
| `multi_prompt_carousel` | N prompts (mix or named journey) → one image each → carousel | `{ "pools": { "name": [...] }, "journeys": { "name": [...] }, "mix": { "name": 0.5 }, "prompt_count": 3, "journey_probability": 0.2 }` |
| `image_edit_carousel` | Source images + edit prompt → carousel of edited (and optionally original) images | `["edit prompt", ...]` |
| `text_to_video` | Take a text reference → generate narrated video → post | `["text reference", ...]` |

### Provision via API

```bash
# 1. List the available starter packs
curl -H "Authorization: Bearer $KEY" https://fellowships4you.com/api/v1/templates

# 2. Clone one as a paused Product on the user's account
curl -X POST -H "Authorization: Bearer $KEY" \
  https://fellowships4you.com/api/v1/templates/dxp-labs-retrofuturism-narrative/clone

# 3. Or create a Product from scratch
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "My Daily Carousel",
    "schedule": "14:00 EST",
    "content_type": "multi_prompt_carousel",
    "model": "futuristic",
    "connection_id": "tiktok:your-brand",
    "prompt_library": {
      "pools": { "characters": ["...", "..."], "scenes": ["...", "..."] },
      "mix": { "characters": 0.5, "scenes": 0.5 },
      "prompt_count": 4
    },
    "prompt_prefix": "TOK"
  }' \
  https://fellowships4you.com/api/v1/products

# 4. Trigger an immediate test run, then unpause
curl -X POST -H "Authorization: Bearer $KEY" https://fellowships4you.com/api/v1/products/<id>/run_now
curl -X POST -H "Authorization: Bearer $KEY" https://fellowships4you.com/api/v1/products/<id>/unpause
```

### Provision via MCP

When `FEATURE_AUTOMATION` is on, the following MCP tools are exposed: `listProducts`, `createProduct`, `showProduct`, `updateProduct`, `destroyProduct`, `pauseProduct`, `unpauseProduct`, `runProductNow`, `listTemplates`, `showTemplate`, `cloneTemplate`. Same JSON shapes as the REST endpoints — your agent can chain them in a single conversation.

---

## 8. 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

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

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

2. Get an API key

Sign up at https://fellowships4you.com/accounts/sign_up
Connect TikTok via OAuth
Generate an API key at https://fellowships4you.com/api-access
Paste the key (starts with spk_) into the Bearer header above
Verify setup with GET /api/v1/connections before paying
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:

{
  "connections": [
    {
      "id": 17,
      "platform": "tiktok",
      "slug": "tiktok:your-brand",
      "display_name": "dxp_labs_iOS",
      "platform_user_id": "7348200000000",
      "token_active": true
    }
  ]
}

Use the slug (e.g. tiktok:your-brand) 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:your-brand"
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:

{
  "connection_id": "tiktok:your-brand",
  "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:

{
  "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:

{
  "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:your-brand
  2. Call createPost with:
       connection_id: "tiktok:your-brand"
       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. Managed automation: Products + Templates

Once your account has FEATURE_AUTOMATION enabled (paid tier), your agent can provision Products — recurring TikTok/IG/Pinterest workflows that run on a cron-style schedule and post automatically. A Product wraps a content_type (the workflow shape), a prompt_library, a schedule, and a connection.

content_types

| content_type | What it does | prompt_library shape | |---|---|---| | single_prompt_carousel | One prompt → N AI images → carousel post | ["prompt", ...] | | multi_prompt_carousel | N prompts (mix or named journey) → one image each → carousel | { "pools": { "name": [...] }, "journeys": { "name": [...] }, "mix": { "name": 0.5 }, "prompt_count": 3, "journey_probability": 0.2 } | | image_edit_carousel | Source images + edit prompt → carousel of edited (and optionally original) images | ["edit prompt", ...] | | text_to_video | Take a text reference → generate narrated video → post | ["text reference", ...] |

Provision via API

# 1. List the available starter packs
curl -H "Authorization: Bearer $KEY" https://fellowships4you.com/api/v1/templates

# 2. Clone one as a paused Product on the user's account
curl -X POST -H "Authorization: Bearer $KEY" \
  https://fellowships4you.com/api/v1/templates/dxp-labs-retrofuturism-narrative/clone

# 3. Or create a Product from scratch
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "My Daily Carousel",
    "schedule": "14:00 EST",
    "content_type": "multi_prompt_carousel",
    "model": "futuristic",
    "connection_id": "tiktok:your-brand",
    "prompt_library": {
      "pools": { "characters": ["...", "..."], "scenes": ["...", "..."] },
      "mix": { "characters": 0.5, "scenes": 0.5 },
      "prompt_count": 4
    },
    "prompt_prefix": "TOK"
  }' \
  https://fellowships4you.com/api/v1/products

# 4. Trigger an immediate test run, then unpause
curl -X POST -H "Authorization: Bearer $KEY" https://fellowships4you.com/api/v1/products/<id>/run_now
curl -X POST -H "Authorization: Bearer $KEY" https://fellowships4you.com/api/v1/products/<id>/unpause

Provision via MCP

When FEATURE_AUTOMATION is on, the following MCP tools are exposed: listProducts, createProduct, showProduct, updateProduct, destroyProduct, pauseProduct, unpauseProduct, runProductNow, listTemplates, showTemplate, cloneTemplate. Same JSON shapes as the REST endpoints — your agent can chain them in a single conversation.

8. 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