Send posts from your tools with the API

Before you start

• The base address is https://growfinch.com/api/v1. Every path on this page sits under it. The list of endpoints is on the API’s feature page; this page shows how to use them.
• An API key made for your businesses (next section).
• The accounts connected. Growfinch publishes only to accounts the workspace owner connected in the console: YouTube, Instagram and X.
• Prefer to ask in plain words? Claude can do all of this for you through the same key: see Use Growfinch with Claude.

Get an API key

The console’s Developer page says Not in this release yet: you can’t make a key yourself. During early access, Growfinch issues keys on request. Write to support at support@growfinch.com with the businesses the key is for and the scopes you need.

Any key can list its businesses, their connections and the items waiting for approval. No scope approves: the contract lists approvals:write, but Growfinch refuses approval to every key, whatever its scopes.

A key starts with mvk_. Growfinch stores only a hash of it, so keep it like a password: in a password manager or your system’s keychain, never in a file you share or commit. If a key leaks, write to support and we’ll revoke it.

Authenticate every request

Send the key in the Authorization header as Bearer, a space, then the key. The examples on this page read it from an environment variable. To set it without it showing on screen or landing in your shell history, run this, paste the key and press Enter:

read -rs GROWFINCH_API_KEY && export GROWFINCH_API_KEY

Then make your first call. It lists the businesses the key may act on:

curl -sS https://growfinch.com/api/v1/businesses \
  -H "Authorization: Bearer $GROWFINCH_API_KEY" \
  -H "x-maovora-contract: 1.2.0"

Each business comes back with its slug, name, timezone, default_mode (its publishing rule) and required_checks. The slug is the business_id you send in every other call. Growfinch never guesses the business.

A minor version may add fields to a response. Ignore the ones you don’t know.

Send a campaign: validate, then create

A campaign is one piece of content for one business: one or more posts, each for one account at its own time. Send it in two steps. Validate is a dry run that writes nothing. Create stores the campaign, and where the business requires approval, files it on Approvals.

1. Write the body

Save this as campaign.json, with your own values in place of the parts in angle brackets:

{
  "business_id": "<business id>",
  "name": "<campaign name>",
  "idempotency_key": "<a new key for this campaign, 8 to 128 characters>",
  "posts": [
    {
      "platform": "youtube",
      "format": "short",
      "title": "<title, 100 characters at most>",
      "caption": "<description>",
      "link": "https://example.com/?utm_content=<your label>",
      "scheduled_at": "2026-11-03T09:00:00Z",
      "media": [{ "media_id": "<media id>", "kind": "video", "sha256": "<sha256>" }]
    },
    {
      "platform": "x",
      "format": "video",
      "caption": "<post text, 280 characters at most>",
      "first_reply": "<your link, posted as the first reply>",
      "scheduled_at": "2026-11-03T09:00:00Z",
      "media": [{ "media_id": "<media id>", "kind": "video", "sha256": "<sha256>" }]
    }
  ]
}

Every one of these formats carries one file, so each post needs its media.

2. Validate it

curl -sS https://growfinch.com/api/v1/campaigns/validate \
  -H "Authorization: Bearer $GROWFINCH_API_KEY" \
  -H "x-maovora-contract: 1.2.0" \
  -H "content-type: application/json" \
  --data @campaign.json

Nothing is stored. The answer has four parts:

• ok: true when every line of the checklist passes.
• checklist: one line per check, each with name, ok and detail. It covers each post’s account (connected, or expired and needing a reconnect), its format, its caption length, YouTube’s title, the earliest time the content may go out, and each check the business requires.
• previews: one per post, with the characters used against the limit and warnings, such as too many hashtags or a field the platform will drop.
• decision: what create would do: draft, pending_approval or scheduled.

You can validate before you upload: in a dry run, a media item may carry only its kind and sha256.

3. Create it

When validation passes, send the same body to /campaigns:

curl -sS https://growfinch.com/api/v1/campaigns \
  -H "Authorization: Bearer $GROWFINCH_API_KEY" \
  -H "x-maovora-contract: 1.2.0" \
  -H "content-type: application/json" \
  --data @campaign.json

A new campaign answers 201 with campaign (its id, status and posts) and replayed: false. A retry with the same idempotency_key answers 200 with the same campaign and replayed: true, so retrying after a timeout is safe.

Upload a video or image

A file reaches Growfinch in three calls: register it, upload the bytes, then confirm. The same file registered twice for the same business is the same record, so a re-run never uploads twice.

1. Register the file with its SHA-256 fingerprint and size. The name may use letters, digits, dots, dashes and underscores, and must end in mp4, mov, png, jpg, jpeg or webp, matching its kind. Files can be up to 512 MB.

FILE=launch.mp4
SHA=$(shasum -a 256 "$FILE" | cut -d' ' -f1)
BYTES=$(wc -c < "$FILE" | tr -d ' ')
curl -sS https://growfinch.com/api/v1/media \
  -H "Authorization: Bearer $GROWFINCH_API_KEY" \
  -H "content-type: application/json" \
  --data "{\"business_id\":\"<business id>\",\"kind\":\"video\",\"filename\":\"$FILE\",\"sha256\":\"$SHA\",\"bytes\":$BYTES}"

The answer holds media (its id and status: pending) and upload: a signed url, the method PUT and the headers to send. You can add width, height and duration_ms to the body if you know them.

2. Upload the bytes to that address, with the header it gave you. This request goes to storage, not to Growfinch, so it takes no API key.

curl -sS -X PUT "<upload url>" \
  -H "content-type: video/mp4" \
  --data-binary @"$FILE"

3. Confirm it arrived. The file is now ready.

curl -sS -X POST https://growfinch.com/api/v1/media/<media id>/complete \
  -H "Authorization: Bearer $GROWFINCH_API_KEY"

Use the id, the kind and the sha256 in each post’s media. GET /media/<media id> shows a file’s status at any time. If the upload address has run out, register the same file again: you get a new one.

Before each post goes out, Growfinch checks that its file is ready and that the sha256 in the post matches the file registered. A post whose file doesn’t match fails rather than publishing something else.

Follow a campaign, or cancel it

curl -sS https://growfinch.com/api/v1/campaigns/<campaign id> \
  -H "Authorization: Bearer $GROWFINCH_API_KEY"

The answer is the campaign with its posts, and events: its history, from creation through approval to each publish. Each post has its status, and once out its permalink and published_at; a failed one has error_code and error_message.

A post is scheduled, publishing, published, failed or cancelled. For what each failure means, see Fix a failed post.

To list a business’s campaigns, use GET /campaigns?business_id=<business id>, with optional status (several, separated by commas, such as scheduled,pending_approval), from, to and limit (50 unless you ask, up to 200).

To cancel, send DELETE with an optional reason:

curl -sS -X DELETE "https://growfinch.com/api/v1/campaigns/<campaign id>?reason=Changed%20plans" \
  -H "Authorization: Bearer $GROWFINCH_API_KEY"

Posts still waiting to go out are cancelled; posts already published stay up. If the campaign was waiting for approval, its approval is closed, and if it was in a queue, it leaves the queue.

Add posts to a queue

A queue is a weekly timetable for one business, and each post you add takes the next free slot. Fill a queue of evergreen posts explains how queues behave; these are the calls.

POST /queues
{
  "business_id": "<business id>",
  "name": "<queue name>",
  "slots": [{ "weekday": "tue", "time": "09:00" }, { "weekday": "thu", "time": "09:00" }],
  "idempotency_key": "<a new key for this queue>"
}

POST /queues/<queue id>/items
{
  "campaign": {
    "name": "<post name>",
    "idempotency_key": "<a new key for this post>",
    "posts": [{ "platform": "instagram", "format": "reel", "caption": "<caption>",
                "media": [{ "media_id": "<media id>", "kind": "video", "sha256": "<sha256>" }] }]
  }
}

Slot times are 24-hour, in the queue’s time zone: the business’s unless you send timezone. A new queue needs approval for each item (mode: approval_required), fills in order (fill: fifo) and posts at most once a day (max_per_day: 1); you can set each of these when you create it. An item’s campaign has no business_id and no scheduled_at: the queue gives both. The answer includes lands_at, the slot it will take if it’s approved now. Instead of a new body you can add an existing draft or pending campaign as { "campaign_id": "<campaign id>" }.

Read results and approvals

curl -sS "https://growfinch.com/api/v1/posts/metrics?business_id=<business id>" \
  -H "Authorization: Bearer $GROWFINCH_API_KEY"

The answer covers the last 30 days unless you send from and to (ISO times). For each published post, posts gives its permalink, meta and attribution_key, its latest and previous daily snapshots, the change between them, and every snapshot in the window. totals adds up each platform over the last 7 and 30 days. A snapshot has views, likes and comments, and shares, watch_time_seconds, average_view_seconds and impressions where the platform reports them. A counter the platform doesn’t give is null; Growfinch never estimates one. Read results explains how the numbers are collected.

GET /approvals lists the items waiting for a person in the businesses your key can see. It’s for reading only: a person approves or rejects in the console (Approve posts).

Report outcomes (1.5.0)

A view on a platform is not a result for your business. With the outcomes:write scope, POST /v1/outcomes takes what happened on your side, by your own event id and the utm_content the session arrived with; Growfinch joins each event to the post whose link carried that key within 7 days of publishing, the latest post winning, and keeps the others as candidates. A click is never an outcome.

curl -s -X POST https://growfinch.com/api/v1/outcomes \
  -H "Authorization: Bearer $GROWFINCH_API_KEY" -H "Content-Type: application/json" \
  -d '{"business_id":"<slug>","events":[{"type":"signup","event_id":"evt_1081","occurred_at":"2026-11-03T14:12:00Z","attribution_key":"2026-11-03-launch-instagram"}]}'

• type: visit · first_play · game_completed · signup · lead · purchase · custom:<snake_case>. event_id is yours and unique per type: the same id again is a duplicate, counted and not written. value is optional (amount_micro, currency); reverses names an event you sent before.
• Up to 500 events a call; send hourly batches. Unknown fields and anything shaped like an answer are refused (422). Never send a user id, an email, a session cookie or an analytics key.
• GET /v1/outcomes?business_id=<slug>&from=&to= lists what Growfinch holds, with the post each was joined to, the counts by type, and how many could not be joined.

How to set the key on your links and your site is on Label your posts and follow them to results.

Get events with webhooks

Instead of asking again and again, let Growfinch tell you when something happens. You need a key with webhooks:write.

1. Register an https address and the events you want (up to 20, or * for all). Add business_ids to limit it to some of your businesses; without it, it covers every business the key may act on.

curl -sS https://growfinch.com/api/v1/webhooks \
  -H "Authorization: Bearer $GROWFINCH_API_KEY" \
  -H "content-type: application/json" \
  --data '{"url":"https://example.com/hooks/growfinch","events":["post.published","post.failed","connection.expired"]}'

2. Save the secret from the answer, beside the endpoint and its id. It’s shown this once and never again. Store it as you store the key.
3. Test it with POST /webhooks/<id>/ping. Growfinch sends a signed webhook.ping now and answers with delivered and the status_code your address returned.

GET /webhooks lists your endpoints (never a secret) and DELETE /webhooks/<id> removes one.

What arrives

Each event is a POST with a JSON body: id, type, created_at, business_id and data. The headers x-maovora-event and x-maovora-delivery name the event type and the delivery.

Check the signature

Every delivery carries x-maovora-signature: t=<unix seconds>,v1=<hex>. The v1 value is an HMAC-SHA256, keyed with your endpoint’s secret, of the timestamp, a dot and the raw body exactly as it arrived. Check it before you trust the body, and refuse a timestamp more than five minutes from now. In Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body exactly as it arrived, before any JSON parsing.
export function verifyGrowfinch(secret, rawBody, header) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec((header ?? "").trim());
  if (!m) return false;
  if (Math.abs(Date.now() / 1000 - Number(m[1])) > 300) return false;
  const expected = createHmac("sha256", secret).update(m[1] + "." + rawBody).digest();
  const given = Buffer.from(m[2], "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Answer with any 2xx status within 10 seconds. Anything else is tried again after about 1, 5, 30, 120 and 720 minutes. A delivery can arrive more than once, so skip an event whose id you’ve already handled.

What Growfinch refuses

• Unknown fields. Every object in a request is closed: a field Growfinch doesn’t know is refused with validation_failed, naming it (Unrecognized key). Check the spelling against this page. Your free-form data goes in payload, and labels for results in meta.
• Fields that could give away an answer. Growfinch never holds an answer, so these field names are refused wherever they appear, at any depth, payload and meta included: answer, answers, solution, place, placename, lat, lng, lon, latitude, longitude, coordinates and coords. Each part of a name counts, split at underscores, dashes and capitals, so place_name, userLat and correctAnswer are refused too. The error is spoiler_field; remove the field and send again.
• A request without its business. Every call that touches a business names it with business_id. A key can only act on the businesses it was made for.
• Approval. No key approves, whatever its scopes. A person approves in the console.

If something goes wrong

Every error has the same shape. details says what to fix, when there’s something to say:

{
  "error": {
    "code": "validation_failed",
    "message": "Validation failed.",
    "request_id": "<request id>",
    "details": [{ "path": "posts.0", "message": "Unrecognized key: \"hashtags\"" }]
  }
}

For posts that failed at the platform after they were scheduled, see Fix a failed post. Questions this page doesn’t answer: write to support, and we’ll add the answer.