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
| Environment | Base URL |
|---|---|
| Production | https://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
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | integer | |
data.email | string | |
data.plan | string | null | |
data.limits | object | |
data.limits.api_requests_per_minute | integer | 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
| Name | In | Type | Description |
|---|---|---|---|
type | query | string | Comma-separated feed types: original, smart, discovery, imported. |
status | query | "active" | "inactive" | Feed status. |
search | query | string | Substring search over feed titles. |
tag | query | string | Comma-separated owned tag ids (1–50). |
cursor | query | string | Opaque signed cursor from the previous page meta. Omit for the first page. |
per_page | query | integer | Page size, 1–100. Default 25. |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<object> | |
data[].id | integer | |
data[].public_id | string | |
data[].title | string | |
data[].slug | string | null | |
data[].type | "original" | "smart" | "discovery" | "imported" | |
data[].status | "active" | "inactive" | |
data[].description | string | null | |
data[].image_url | string | null | |
data[].source_url | string | null | |
data[].source_name | string | null | |
data[].settings | object | null | Discovery-catalog stats subset (language, per_week, partial, subscribers). Null for other feed types. |
data[].item_count | integer | |
data[].created_at | string | null | |
data[].last_synced_at | string | null | |
data[].tags | array<object> | |
data[].tags[].id | integer | |
data[].tags[].name | string | |
data[].tags[].slug | string | |
data[].tags[].color | string | null | |
meta | object | |
meta.per_page | integer | |
meta.next_cursor | string | null | |
meta.has_more | boolean |
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
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key (required) | header | string | Required. 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
| Field | Type | Description |
|---|---|---|
title (required) | string | |
slug | string | null | |
description | string | null | |
tag_ids | array<integer> | null | |
image_url | string | null |
Response 201
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.public_id | string | |
data.title | string | |
data.slug | string | |
data.type | string | |
data.status | string | |
data.description | string | |
data.image_url | string | null | |
data.source_url | string | null | |
data.source_name | array<any> | null | string | integer | object | |
data.settings | array<any> | null | |
data.item_count | string | |
data.created_at | string | null | |
data.last_synced_at | string | null | |
data.tags | string | 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
| Name | In | Type | Description |
|---|---|---|---|
feed (required) | path | integer |
Response 200
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | integer | |
data.public_id | string | |
data.title | string | |
data.slug | string | null | |
data.type | "original" | "smart" | "discovery" | "imported" | |
data.status | "active" | "inactive" | |
data.description | string | null | |
data.image_url | string | null | |
data.source_url | string | null | |
data.source_name | string | null | |
data.settings | object | null | Discovery-catalog stats subset (language, per_week, partial, subscribers). Null for other feed types. |
data.item_count | integer | |
data.created_at | string | null | |
data.last_synced_at | string | null | |
data.tags | array<object> | |
data.tags[].id | integer | |
data.tags[].name | string | |
data.tags[].slug | string | |
data.tags[].color | string | 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
| Name | In | Type | Description |
|---|---|---|---|
feed (required) | path | integer | |
Idempotency-Key (required) | header | string | Required. 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
| Field | Type | Description |
|---|---|---|
title | string | |
slug | string | |
description | string | null | |
status | "active" | "inactive" | |
tag_ids | array<integer> | null | |
image_url | string | null |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<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
| Name | In | Type | Description |
|---|---|---|---|
feed (required) | path | integer | |
Idempotency-Key | header | string | Optional. 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
| Name | In | Type | Description |
|---|---|---|---|
feed (required) | path | integer | |
cursor | query | string | Opaque signed cursor from the previous page meta. Omit for the first page. |
per_page | query | integer | Page 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
| Name | In | Type | Description |
|---|---|---|---|
feed | query | integer | Restrict to one owned Original feed. |
status | query | "published" | "scheduled" | "draft" | Post status. |
cursor | query | string | Opaque signed cursor from the previous page meta. Omit for the first page. |
per_page | query | integer | Page size, 1–100. Default 25. |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<object> | |
data[].id | integer | null | Null for smart-feed snapshot rows, which have no database id — `guid` is the stable identity there. |
data[].feed_id | integer | |
data[].guid | string | |
data[].title | string | null | |
data[].slug | string | null | |
data[].status | "published" | "scheduled" | "draft" | |
data[].url | string | null | |
data[].original_url | string | null | |
data[].description | string | null | |
data[].body | string | null | |
data[].image_url | string | null | |
data[].source_title | string | null | |
data[].source_url | string | null | |
data[].author | string | null | |
data[].categories | array<string> | null | |
data[].published_at | string | null | |
data[].scheduled_at | string | null | |
data[].created_at | string | null | |
data[].updated_at | string | null | |
meta | object | |
meta.per_page | integer | |
meta.next_cursor | string | null | |
meta.has_more | boolean |
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
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key (required) | header | string | Required. 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
| Field | Type | Description |
|---|---|---|
feed_id (required) | integer | |
title (required) | string | |
slug | string | null | |
body | string | null | |
author | string | null | |
tag_ids | array<integer> | null | |
image_url | string | null | |
status (required) | "published" | "scheduled" | "draft" | |
scheduled_at | string |
Response 201
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | string | |
data.feed_id | string | |
data.guid | string | |
data.title | string | |
data.slug | string | |
data.status | string | |
data.url | string | null | |
data.original_url | string | null | |
data.description | string | |
data.body | string | |
data.image_url | string | null | |
data.source_title | string | |
data.source_url | string | null | |
data.author | string | |
data.categories | string | |
data.published_at | string | null | |
data.scheduled_at | string | null | |
data.created_at | string | null | |
data.updated_at | string | null | |
data.feed | object | null | object | |
data.tags | string | 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
| Name | In | Type | Description |
|---|---|---|---|
post (required) | path | integer |
Response 200
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | integer | null | Null for smart-feed snapshot rows, which have no database id — `guid` is the stable identity there. |
data.feed_id | integer | |
data.guid | string | |
data.title | string | null | |
data.slug | string | null | |
data.status | "published" | "scheduled" | "draft" | |
data.url | string | null | |
data.original_url | string | null | |
data.description | string | null | |
data.body | string | null | |
data.image_url | string | null | |
data.source_title | string | null | |
data.source_url | string | null | |
data.author | string | null | |
data.categories | array<string> | null | |
data.published_at | string | null | |
data.scheduled_at | string | null | |
data.created_at | string | null | |
data.updated_at | string | 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
| Name | In | Type | Description |
|---|---|---|---|
post (required) | path | integer | |
Idempotency-Key (required) | header | string | Required. 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
| Field | Type | Description |
|---|---|---|
feed_id | integer | |
title | string | |
slug | string | |
body | string | null | |
author | string | null | |
tag_ids | array<integer> | null | |
image_url | string | null | |
status | "published" | "scheduled" | "draft" | |
scheduled_at | string |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<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
| Name | In | Type | Description |
|---|---|---|---|
post (required) | path | integer | |
Idempotency-Key | header | string | Optional. 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
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | Opaque signed cursor from the previous page meta. Omit for the first page. |
per_page | query | integer | Page size, 1–100. Default 25. |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<object> | |
data[].id | integer | |
data[].public_id | string | |
data[].channel_id | string | null | |
data[].provider | string | |
data[].name | string | |
data[].avatar_url | string | null | |
data[].public_url | string | null | |
data[].target_kind | string | null | |
data[].capabilities | array<string> | |
data[].connected_at | string | null | |
data[].needs_reconnect | boolean | |
data[].verified | boolean | null | |
data[].overage_disabled | boolean | |
meta | object | |
meta.per_page | integer | |
meta.next_cursor | string | null | |
meta.has_more | boolean |
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
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | Opaque signed cursor from the previous page meta. Omit for the first page. |
per_page | query | integer | Page size, 1–100. Default 25. |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<object> | |
data[].id | integer | |
data[].public_id | string | |
data[].name | string | |
data[].status | "draft" | "running" | "paused" | "error" | |
data[].destination | string | |
data[].timezone | string | |
data[].schedule_type | string | |
data[].start_at | string | null | |
data[].stop_at | string | null | |
data[].next_run_at | string | null | |
data[].last_run_at | string | null | |
data[].consecutive_failures | integer | |
data[].created_at | string | null | |
data[].updated_at | string | null | |
data[].feeds_count | integer | |
data[].feeds | array<object> | |
data[].feeds[].id | integer | |
data[].feeds[].public_id | string | |
data[].feeds[].title | string | |
data[].feeds[].image_url | string | null | |
data[].feeds[].source_url | string | null | |
meta | object | |
meta.per_page | integer | |
meta.next_cursor | string | null | |
meta.has_more | boolean |
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
| Name | In | Type | Description |
|---|---|---|---|
publisher (required) | path | integer |
Response 200
| Field | Type | Description |
|---|---|---|
data | object | |
data.id | integer | |
data.public_id | string | |
data.name | string | |
data.status | "draft" | "running" | "paused" | "error" | |
data.destination | string | |
data.timezone | string | |
data.schedule_type | string | |
data.start_at | string | null | |
data.stop_at | string | null | |
data.next_run_at | string | null | |
data.last_run_at | string | null | |
data.consecutive_failures | integer | |
data.created_at | string | null | |
data.updated_at | string | null | |
data.feeds_count | integer | |
data.feeds | array<object> | |
data.feeds[].id | integer | |
data.feeds[].public_id | string | |
data.feeds[].title | string | |
data.feeds[].image_url | string | null | |
data.feeds[].source_url | string | 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
| Name | In | Type | Description |
|---|---|---|---|
cursor | query | string | Opaque signed cursor from the previous page meta. Omit for the first page. |
per_page | query | integer | Page size, 1–100. Default 25. |
Response 200
| Field | Type | Description |
|---|---|---|
data | array<object> | |
data[].id | integer | |
data[].name | string | |
data[].slug | string | |
data[].color | string | null | |
meta | object | |
meta.per_page | integer | |
meta.next_cursor | string | null | |
meta.has_more | boolean |
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
| Field | Type | Description |
|---|---|---|
event | "channel.token_expired" | |
event_id | string | Stable id "channel.token_expired:<integrationId>:<uuid>" — prefixed, not a bare UUID. Dedupe on this — retries repeat it with the same body. |
version | integer | Payload version. A breaking shape change ships a new version. |
occurred_at | string | ISO 8601 UTC timestamp of the source event. |
data | object | |
data.integration | object | |
data.integration.id | integer | |
data.integration.provider | string | |
data.integration.label | string | Safe display label — never a credential. |
data.reason | string | Internal code such as provider_rejected_refresh. |
post.published
| Field | Type | Description |
|---|---|---|
event | "post.published" | |
event_id | string | Stable UUID of the publication episode. Dedupe on this — retries repeat it with the same body. |
version | integer | Payload version. A breaking shape change ships a new version. |
occurred_at | string | ISO 8601 UTC timestamp of the source event. |
data | object | |
data.post | object | |
data.post.id | integer | |
data.post.guid | string | |
data.post.title | string | |
data.post.url | string | null | |
data.post.excerpt | string | null | Plain-text excerpt, at most 2000 characters. |
data.post.image_url | string | null | |
data.post.author | string | null | |
data.post.published_at | string | null | |
data.post.tags | array<string> | |
data.feed | object | null | |
data.feed.id | integer | |
data.feed.title | string | |
data.feed.url | string | null |
publisher.run.failed
| Field | Type | Description |
|---|---|---|
event | "publisher.run.failed" | |
event_id | string | Stable id "publisher.run.failed:<uuid>" — prefixed, not a bare UUID. Dedupe on this — retries repeat it with the same body. |
version | integer | Payload version. A breaking shape change ships a new version. |
occurred_at | string | ISO 8601 UTC timestamp of the source event. |
data | object | |
data.publisher | object | |
data.publisher.id | integer | |
data.publisher.name | string | |
data.publisher.destination | string | |
data.error | object | |
data.error.code | "run_failed" | "credentials_rejected" | |
data.error.message | string | |
data.consecutive_failures | integer | |
data.occurrence_id | integer | 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.
