Ferryman API

1. Open Settings, expand AI Tools and generate an API key. Copy it: it is shown once.
2. List the platforms you can post to:

export FERRYMAN_API_KEY=fky_live_...
curl https://ferryman.io/api/v1/connections -H "Authorization: Bearer $FERRYMAN_API_KEY"

3. Schedule a post. Leave out scheduledAt to publish right away, or add "dryRun": true to see exactly what would happen without posting.

curl -X POST https://ferryman.io/api/v1/posts \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"New guide is live","platforms":["BLUESKY","THREADS"],"scheduledAt":"2026-11-02T14:00:00Z"}'

Every request sends an API key as a bearer token: Authorization: Bearer fky_live_.... Keys are created and revoked in Settings, and work for both this API and the Ferryman MCP server.

A key can post to every connected account as you. Keep it on your server, never in browser code or a public repo. If one leaks, revoke it in Settings and generate a new one.

• 120 requests per minute per API key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
• 60 publishes and schedules per hour per account, shared with the MCP server.
• 60 media uploads per hour per account.

Over a limit the API answers 429 with a Retry-After header in seconds.

Every error has the same JSON shape, with an HTTP status that matches its type:

{
  "error": {
    "type": "invalid_request",
    "message": "scheduledAt must be in the future."
  }
}

When a publish reaches some platforms but not others, the call still succeeds: each platform's outcome is in results.

Base URL https://ferryman.io/api/v1. Bodies are JSON. The full machine-readable description is the OpenAPI spec.

curl https://ferryman.io/api/v1/connections \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl -X POST https://ferryman.io/api/v1/media \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"clip.mp4","contentType":"video/mp4"}'

curl -X POST https://ferryman.io/api/v1/posts \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"New guide is live","platforms":["BLUESKY","THREADS"],"scheduledAt":"2026-11-02T14:00:00Z"}'

curl -X POST https://ferryman.io/api/v1/threads \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"posts":[{"text":"1/ How we cut posting time in half"},{"text":"2/ Write once, schedule everywhere"}],"platforms":["TWITTER","BLUESKY"]}'

curl https://ferryman.io/api/v1/scheduled-posts \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl -X PATCH https://ferryman.io/api/v1/scheduled-posts/cmv8a1b2c0001 \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt":"2026-11-03T09:30:00Z"}'

curl -X DELETE https://ferryman.io/api/v1/scheduled-posts/cmv8a1b2c0001 \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl https://ferryman.io/api/v1/platform-groups \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl https://ferryman.io/api/v1/platform-groups/cmv8a1b2c0001/slots \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl -X PUT https://ferryman.io/api/v1/platform-groups/cmv8a1b2c0001/posting-schedule \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"timezone":"America/New_York","times":{"monday":["09:00","17:30"],"wednesday":["12:00"]}}'

curl -X DELETE https://ferryman.io/api/v1/platform-groups/cmv8a1b2c0001/posting-schedule \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl https://ferryman.io/api/v1/webhooks \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

curl -X POST https://ferryman.io/api/v1/webhooks \
  -H "Authorization: Bearer $FERRYMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/ferryman/webhook","events":["post.published","post.failed"]}'

curl -X DELETE https://ferryman.io/api/v1/webhooks/cmv8a1b2c0001 \
  -H "Authorization: Bearer $FERRYMAN_API_KEY"

Add an endpoint in Settings, under Webhooks, or with POST /webhooks. Ferryman sends it an HTTP POST with a JSON body for each event you subscribe to:

• post.scheduled - a post was scheduled, from the API, an AI tool or the Ferryman app.
• post.published - a scheduled post, or a post published through the API or MCP, reached at least one platform. Platforms that failed are listed in results.
• post.failed - every platform failed.
• A video published right away through the API or MCP uploads in the background: it is listed as processing, and its final result is not sent as a webhook yet. Schedule a video, even a minute ahead, to get its outcome.
• webhook.test - sent by the Send test button in Settings.

{
  "id": "evt_3f9c2a",
  "type": "post.scheduled",
  "createdAt": "2026-11-01T18:00:00.000Z",
  "data": {
    "scheduledPostId": "cmv8a1b2c0001",
    "platforms": [
      "BLUESKY",
      "THREADS"
    ],
    "scheduledAt": "2026-11-02T14:00:00.000Z",
    "text": "New guide is live",
    "isThread": false,
    "source": "api"
  }
}

{
  "id": "evt_7d41b0",
  "type": "post.published",
  "createdAt": "2026-11-02T14:00:07.000Z",
  "data": {
    "postId": "cmv8a1b2c0001",
    "scheduled": true,
    "platforms": [
      "BLUESKY",
      "THREADS"
    ],
    "text": "New guide is live",
    "results": [
      {
        "platform": "BLUESKY",
        "success": true,
        "status": "published",
        "postId": "at://did:plc:abc/app.bsky.feed.post/3k",
        "url": "https://bsky.app/profile/you.bsky.social/post/3k"
      },
      {
        "platform": "THREADS",
        "success": false,
        "status": "failed",
        "error": "Threads rejected the post"
      }
    ]
  }
}

Verify the signature

Each request carries Ferryman-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of <t>.<raw body> keyed with the endpoint's secret (whsec_..., shown once when you add the endpoint). Ferryman-Event-Id and Ferryman-Event-Type headers repeat the event's id and type.

import crypto from "node:crypto";

// rawBody: the exact request body bytes, before JSON.parse
export function verifyFerrymanWebhook(rawBody, signatureHeader, secret) {
    const parts = Object.fromEntries(
        signatureHeader.split(",").map(part => part.split("="))
    );
    const timestamp = Number(parts.t);
    // Reject events older than 5 minutes (replay protection)
    if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

    const expected = crypto
        .createHmac("sha256", secret)
        .update(`${timestamp}.${rawBody}`)
        .digest("hex");
    const received = Buffer.from(parts.v1 ?? "", "hex");
    const wanted = Buffer.from(expected, "hex");
    return received.length === wanted.length && crypto.timingSafeEqual(received, wanted);
}

Retries

Answer with any 2xx status within 10 seconds. Otherwise Ferryman retries after 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, 24 hours (7 attempts in total), then marks the delivery failed. Retries keep the same event id, so store ids you have handled and ignore repeats. Settings shows every endpoint's recent deliveries with their status and response code.