Pular para o conteúdo

API reference

Feedigy public API v1. Bearer tokens only; versioned path; cursor pagination; idempotent writes; signed event webhooks.

Start with the quickstart; limits, errors and retries are in the policies. The machine-readable contract is openapi.json (OpenAPI 3.1.0, version 1.0.0).

Base URLs and auth

EnvironmentBase URL
Productionhttps://api.feedigy.com/v1

Create a token in Settings → API. Send it as `Authorization: Bearer <token>`. No cookies, no CSRF.

Me

GET /me

Token ability: account:read

Response 200
FieldTypeDescription
dataobject
data.idinteger
data.emailstring
data.planstring | null
data.limitsobject
data.limits.api_requests_per_minuteinteger | null

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

Feed

GET /feeds

Token ability: feeds:read

Parameters

NameInTypeDescription
typequerystringComma-separated feed types: original, smart, discovery, imported.
statusquery"active" | "inactive"Feed status.
searchquerystringSubstring search over feed titles.
tagquerystringComma-separated owned tag ids (1–50).
cursorquerystringOpaque signed cursor from the previous page meta. Omit for the first page.
per_pagequeryintegerPage size, 1–100. Default 25.
Response 200
FieldTypeDescription
dataarray<object>
data[].idinteger
data[].public_idstring
data[].titlestring
data[].slugstring | null
data[].type"original" | "smart" | "discovery" | "imported"
data[].status"active" | "inactive"
data[].descriptionstring | null
data[].image_urlstring | null
data[].source_urlstring | null
data[].source_namestring | null
data[].settingsobject | nullDiscovery-catalog stats subset (language, per_week, partial, subscribers). Null for other feed types.
data[].item_countinteger
data[].created_atstring | null
data[].last_synced_atstring | null
data[].tagsarray<object>
data[].tags[].idinteger
data[].tags[].namestring
data[].tags[].slugstring
data[].tags[].colorstring | null
metaobject
meta.per_pageinteger
meta.next_cursorstring | null
meta.has_moreboolean

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

POST /feeds

Token ability: feeds:write

Parameters

NameInTypeDescription
Idempotency-Key (required)headerstringRequired. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.

Request body

FieldTypeDescription
title (required)string
slugstring | null
descriptionstring | null
tag_idsarray<integer> | null
image_urlstring | null
Response 201
FieldTypeDescription
dataobject
data.idstring
data.public_idstring
data.titlestring
data.slugstring
data.typestring
data.statusstring
data.descriptionstring
data.image_urlstring | null
data.source_urlstring | null
data.source_namearray<any> | null | string | integer | object
data.settingsarray<any> | null
data.item_countstring
data.created_atstring | null
data.last_synced_atstring | null
data.tagsstring | object

Errors

  • 400The request body is not valid JSON.
  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 409A request with this idempotency key is already in progress. Wait a second and retry with the same key.
  • 413The request body exceeds the 256 KB limit.
  • 415Write requests must use Content-Type: application/json.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

GET /feeds/{feed}

Token ability: feeds:read

Parameters

NameInTypeDescription
feed (required)pathinteger
Response 200
FieldTypeDescription
dataobject
data.idinteger
data.public_idstring
data.titlestring
data.slugstring | null
data.type"original" | "smart" | "discovery" | "imported"
data.status"active" | "inactive"
data.descriptionstring | null
data.image_urlstring | null
data.source_urlstring | null
data.source_namestring | null
data.settingsobject | nullDiscovery-catalog stats subset (language, per_week, partial, subscribers). Null for other feed types.
data.item_countinteger
data.created_atstring | null
data.last_synced_atstring | null
data.tagsarray<object>
data.tags[].idinteger
data.tags[].namestring
data.tags[].slugstring
data.tags[].colorstring | null

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

PATCH /feeds/{feed}

Token ability: feeds:write

Parameters

NameInTypeDescription
feed (required)pathinteger
Idempotency-Key (required)headerstringRequired. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.

Request body

FieldTypeDescription
titlestring
slugstring
descriptionstring | null
status"active" | "inactive"
tag_idsarray<integer> | null
image_urlstring | null
Response 200
FieldTypeDescription
dataarray<any>

Errors

  • 400The request body is not valid JSON.
  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 409A request with this idempotency key is already in progress. Wait a second and retry with the same key.
  • 413The request body exceeds the 256 KB limit.
  • 415Write requests must use Content-Type: application/json.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

DELETE /feeds/{feed}

Token ability: feeds:write

Parameters

NameInTypeDescription
feed (required)pathinteger
Idempotency-KeyheaderstringOptional. Same semantics as POST/PATCH when present; without it a repeat DELETE meets the already-deleted record as a 404.
Response 204 (no body)

Errors

  • 400The request body is not valid JSON.
  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 409A request with this idempotency key is already in progress. Wait a second and retry with the same key.
  • 413The request body exceeds the 256 KB limit.
  • 415Write requests must use Content-Type: application/json.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

FeedItem

GET /feeds/{feed}/items

Token ability: feeds:read

Items of Original feeds additionally require the posts:read ability.

Parameters

NameInTypeDescription
feed (required)pathinteger
cursorquerystringOpaque signed cursor from the previous page meta. Omit for the first page.
per_pagequeryintegerPage size, 1–100. Default 25.
Response 200 (no body)

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

Post

GET /posts

Token ability: posts:read

Parameters

NameInTypeDescription
feedqueryintegerRestrict to one owned Original feed.
statusquery"published" | "scheduled" | "draft"Post status.
cursorquerystringOpaque signed cursor from the previous page meta. Omit for the first page.
per_pagequeryintegerPage size, 1–100. Default 25.
Response 200
FieldTypeDescription
dataarray<object>
data[].idinteger | nullNull for smart-feed snapshot rows, which have no database id — `guid` is the stable identity there.
data[].feed_idinteger
data[].guidstring
data[].titlestring | null
data[].slugstring | null
data[].status"published" | "scheduled" | "draft"
data[].urlstring | null
data[].original_urlstring | null
data[].descriptionstring | null
data[].bodystring | null
data[].image_urlstring | null
data[].source_titlestring | null
data[].source_urlstring | null
data[].authorstring | null
data[].categoriesarray<string> | null
data[].published_atstring | null
data[].scheduled_atstring | null
data[].created_atstring | null
data[].updated_atstring | null
metaobject
meta.per_pageinteger
meta.next_cursorstring | null
meta.has_moreboolean

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

POST /posts

Token ability: posts:write

Parameters

NameInTypeDescription
Idempotency-Key (required)headerstringRequired. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.

Request body

FieldTypeDescription
feed_id (required)integer
title (required)string
slugstring | null
bodystring | null
authorstring | null
tag_idsarray<integer> | null
image_urlstring | null
status (required)"published" | "scheduled" | "draft"
scheduled_atstring
Response 201
FieldTypeDescription
dataobject
data.idstring
data.feed_idstring
data.guidstring
data.titlestring
data.slugstring
data.statusstring
data.urlstring | null
data.original_urlstring | null
data.descriptionstring
data.bodystring
data.image_urlstring | null
data.source_titlestring
data.source_urlstring | null
data.authorstring
data.categoriesstring
data.published_atstring | null
data.scheduled_atstring | null
data.created_atstring | null
data.updated_atstring | null
data.feedobject | null | object
data.tagsstring | object

Errors

  • 400The request body is not valid JSON.
  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 409A request with this idempotency key is already in progress. Wait a second and retry with the same key.
  • 413The request body exceeds the 256 KB limit.
  • 415Write requests must use Content-Type: application/json.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

GET /posts/{post}

Token ability: posts:read

Parameters

NameInTypeDescription
post (required)pathinteger
Response 200
FieldTypeDescription
dataobject
data.idinteger | nullNull for smart-feed snapshot rows, which have no database id — `guid` is the stable identity there.
data.feed_idinteger
data.guidstring
data.titlestring | null
data.slugstring | null
data.status"published" | "scheduled" | "draft"
data.urlstring | null
data.original_urlstring | null
data.descriptionstring | null
data.bodystring | null
data.image_urlstring | null
data.source_titlestring | null
data.source_urlstring | null
data.authorstring | null
data.categoriesarray<string> | null
data.published_atstring | null
data.scheduled_atstring | null
data.created_atstring | null
data.updated_atstring | null

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

PATCH /posts/{post}

Token ability: posts:write

Parameters

NameInTypeDescription
post (required)pathinteger
Idempotency-Key (required)headerstringRequired. 1–255 printable ASCII characters. Replaying a key returns the original response; a different request under the same key is a 422. Kept 24 h.

Request body

FieldTypeDescription
feed_idinteger
titlestring
slugstring
bodystring | null
authorstring | null
tag_idsarray<integer> | null
image_urlstring | null
status"published" | "scheduled" | "draft"
scheduled_atstring
Response 200
FieldTypeDescription
dataarray<any>

Errors

  • 400The request body is not valid JSON.
  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 409A request with this idempotency key is already in progress. Wait a second and retry with the same key.
  • 413The request body exceeds the 256 KB limit.
  • 415Write requests must use Content-Type: application/json.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

DELETE /posts/{post}

Token ability: posts:write

Parameters

NameInTypeDescription
post (required)pathinteger
Idempotency-KeyheaderstringOptional. Same semantics as POST/PATCH when present; without it a repeat DELETE meets the already-deleted record as a 404.
Response 204 (no body)

Errors

  • 400The request body is not valid JSON.
  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 409A request with this idempotency key is already in progress. Wait a second and retry with the same key.
  • 413The request body exceeds the 256 KB limit.
  • 415Write requests must use Content-Type: application/json.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

Channel

GET /channels

Token ability: channels:read

Parameters

NameInTypeDescription
cursorquerystringOpaque signed cursor from the previous page meta. Omit for the first page.
per_pagequeryintegerPage size, 1–100. Default 25.
Response 200
FieldTypeDescription
dataarray<object>
data[].idinteger
data[].public_idstring
data[].channel_idstring | null
data[].providerstring
data[].namestring
data[].avatar_urlstring | null
data[].public_urlstring | null
data[].target_kindstring | null
data[].capabilitiesarray<string>
data[].connected_atstring | null
data[].needs_reconnectboolean
data[].verifiedboolean | null
data[].overage_disabledboolean
metaobject
meta.per_pageinteger
meta.next_cursorstring | null
meta.has_moreboolean

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

Publisher

GET /publishers

Token ability: publishers:read

Parameters

NameInTypeDescription
cursorquerystringOpaque signed cursor from the previous page meta. Omit for the first page.
per_pagequeryintegerPage size, 1–100. Default 25.
Response 200
FieldTypeDescription
dataarray<object>
data[].idinteger
data[].public_idstring
data[].namestring
data[].status"draft" | "running" | "paused" | "error"
data[].destinationstring
data[].timezonestring
data[].schedule_typestring
data[].start_atstring | null
data[].stop_atstring | null
data[].next_run_atstring | null
data[].last_run_atstring | null
data[].consecutive_failuresinteger
data[].created_atstring | null
data[].updated_atstring | null
data[].feeds_countinteger
data[].feedsarray<object>
data[].feeds[].idinteger
data[].feeds[].public_idstring
data[].feeds[].titlestring
data[].feeds[].image_urlstring | null
data[].feeds[].source_urlstring | null
metaobject
meta.per_pageinteger
meta.next_cursorstring | null
meta.has_moreboolean

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

GET /publishers/{publisher}

Token ability: publishers:read

Parameters

NameInTypeDescription
publisher (required)pathinteger
Response 200
FieldTypeDescription
dataobject
data.idinteger
data.public_idstring
data.namestring
data.status"draft" | "running" | "paused" | "error"
data.destinationstring
data.timezonestring
data.schedule_typestring
data.start_atstring | null
data.stop_atstring | null
data.next_run_atstring | null
data.last_run_atstring | null
data.consecutive_failuresinteger
data.created_atstring | null
data.updated_atstring | null
data.feeds_countinteger
data.feedsarray<object>
data.feeds[].idinteger
data.feeds[].public_idstring
data.feeds[].titlestring
data.feeds[].image_urlstring | null
data.feeds[].source_urlstring | null

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 404No such record for this account. Foreign ids are 404, never 403.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

Tag

GET /tags

Token ability: feeds:read

Parameters

NameInTypeDescription
cursorquerystringOpaque signed cursor from the previous page meta. Omit for the first page.
per_pagequeryintegerPage size, 1–100. Default 25.
Response 200
FieldTypeDescription
dataarray<object>
data[].idinteger
data[].namestring
data[].slugstring
data[].colorstring | null
metaobject
meta.per_pageinteger
meta.next_cursorstring | null
meta.has_moreboolean

Errors

  • 401Missing, revoked or expired bearer token.
  • 403The token lacks the required ability, or the plan grants no API access.
  • 422The request was well-formed but semantically invalid. A tampered, foreign or filter-mismatched pagination cursor is an invalid_cursor — start over from the first page. Reusing an idempotency key with a different request is an idempotency_key_reused — mint a fresh key per logical operation.
  • 429Per-token plan budget exhausted. Back off for Retry-After seconds.
  • 503The API is disabled or rate limiting is temporarily unavailable. Retry with backoff.

See policies for the error envelope.

Webhook events

Each delivery is a signed POST to your webhook channel. The quickstart shows how to verify the signature.

channel.token_expired
FieldTypeDescription
event"channel.token_expired"
event_idstringStable id "channel.token_expired:<integrationId>:<uuid>" — prefixed, not a bare UUID. Dedupe on this — retries repeat it with the same body.
versionintegerPayload version. A breaking shape change ships a new version.
occurred_atstringISO 8601 UTC timestamp of the source event.
dataobject
data.integrationobject
data.integration.idinteger
data.integration.providerstring
data.integration.labelstringSafe display label — never a credential.
data.reasonstringInternal code such as provider_rejected_refresh.
post.published
FieldTypeDescription
event"post.published"
event_idstringStable UUID of the publication episode. Dedupe on this — retries repeat it with the same body.
versionintegerPayload version. A breaking shape change ships a new version.
occurred_atstringISO 8601 UTC timestamp of the source event.
dataobject
data.postobject
data.post.idinteger
data.post.guidstring
data.post.titlestring
data.post.urlstring | null
data.post.excerptstring | nullPlain-text excerpt, at most 2000 characters.
data.post.image_urlstring | null
data.post.authorstring | null
data.post.published_atstring | null
data.post.tagsarray<string>
data.feedobject | null
data.feed.idinteger
data.feed.titlestring
data.feed.urlstring | null
publisher.run.failed
FieldTypeDescription
event"publisher.run.failed"
event_idstringStable id "publisher.run.failed:<uuid>" — prefixed, not a bare UUID. Dedupe on this — retries repeat it with the same body.
versionintegerPayload version. A breaking shape change ships a new version.
occurred_atstringISO 8601 UTC timestamp of the source event.
dataobject
data.publisherobject
data.publisher.idinteger
data.publisher.namestring
data.publisher.destinationstring
data.errorobject
data.error.code"run_failed" | "credentials_rejected"
data.error.messagestring
data.consecutive_failuresinteger
data.occurrence_idinteger | null

Keep posting through busy weeks

Set sources, keywords and posting hours once. Feedigy posts to your channels while you work on other things.

No card required. The Free plan has no time limit.