API reference

1Authentication

Every request carries a personal API token in the Authorization header. Create one on the API tokens page. The whole token is shown once, when you create it: we keep only a hash of it, so copy it then. You can revoke a token at any time, and an expired or revoked token stops working at once.

curl https://magpiefeed.com/api/v1/me/ \
  -H "Authorization: Bearer mf_AbC123dEf456_your-secret"

The API accepts only tokens. Browser cookies are ignored, so a signed-in browser tab cannot be used to call it. A token can be pinned to one Brand; it then sees only that Brand's data. The API is checked against your plan on every request: if the plan changes to one without the API, the token gets 403 plan_required until the plan includes it again.

Treat a token like a password. Keep it in a secret store, never in page source or a public repository. If one leaks, revoke it and create another.

The same tokens also work on the older Studio endpoints under /api/v1/studio/ (exports and marking a post posted or skipped).

2Scopes

3Rate limits

Each token may make 60/min requests. Over that, the answer is 429 rate_limited with a Retry-After header in seconds. A feed can be asked to poll at most once every two minutes, and one account can ask for at most ten polls in ten minutes (a 429 carries Retry-After).

4Errors

Errors are JSON with a stable code and a sentence you can show to a person:

{"error": {"code": "invalid_request",
           "message": "Some fields are missing or invalid.",
           "fields": {"caption": ["A caption is required."]}}}

5Lists and pagination

List endpoints answer {"data": [...], "pagination": {...}}. Pass limit (default 50, at most 200) and offset; when has_more is true, ask again with offset=next_offset. Times are ISO 8601 in UTC.

6Me

Your account, plan, the token making the call (prefix, scopes, Brand, expiry; never the secret) and its rate limit.

7Brands and channels

The Brands this token can see.

Connected Channels, optionally ?brand=. Platform, name, health and whether it can publish. Credentials are never returned.

curl "https://magpiefeed.com/api/v1/channels/?brand=12" -H "Authorization: Bearer $MF_TOKEN"

8Posts

Newest first. Filters: status (one or a comma list of queued, rendering, ready, publishing, published, published_manual, failed, skipped), brand, channel, and since (changed at or after this time, for syncing). awaiting_approval tells you whether the post is still waiting for a yes.

curl "https://magpiefeed.com/api/v1/posts/?status=ready&since=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $MF_TOKEN"

One post.

Queue a post for a Brand. It lands in your Queue like any other post.

curl -X POST https://magpiefeed.com/api/v1/posts/ \
  -H "Authorization: Bearer $MF_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: spring-sale-2026-10-01" \
  -d '{"brand": 12, "channel": 34,
       "caption": "Spring sale starts today. {LINK}",
       "link": "https://example.com/sale",
       "media_url": "https://example.com/img/sale.png",
       "scheduled_for": "2026-10-01T09:00:00Z"}'

Send an Idempotency-Key header to make retries safe: the same key within 24 hours returns the post the first request made instead of queueing a second one.

9Feeds

Your Feeds, optionally ?brand=: kind, type, status, item count and poll times. A feed's own access header is never returned, and credentials in its URL are masked.

Ask for a poll now instead of waiting for the next scheduled one. Answers 202; the poll runs in the background.

curl -X POST https://magpiefeed.com/api/v1/feeds/56/poll/ -H "Authorization: Bearer $MF_TOKEN"

10Push items into a feed

Send a new product or article the moment it exists, instead of waiting for a poll. A new guid becomes an Item and a new item event, which your Automations react to exactly as they do to a polled one. The same guid again returns the existing Item with 200 and changes nothing, so retries are safe.

curl -X POST https://magpiefeed.com/api/v1/items/ \
  -H "Authorization: Bearer $MF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feed": 56, "guid": "sku-1042", "title": "Linen shirt",
       "url": "https://example.com/p/1042",
       "image_url": "https://example.com/img/1042.jpg",
       "price": "49.00", "currency": "EUR", "availability": "in stock"}'

An item you push into a feed that is also polled is treated like any other item of that feed: if the feed's own document never lists it, later polls count it as gone. Push into a feed whose document you control, or keep a feed just for pushed items.

11Versioning

Everything here is /api/v1/. Within v1 we only add: new endpoints, new optional fields and new fields in answers. Anything that would break a working integration goes into a v2, announced here first.