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: 401, 403, 429, 503. 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: 401, 403, 404, 422, 429, 503. See policies for the error envelope.

POST /feeds

Token ability: feeds:write

Parameters

Name	In	Type	Description
Idempotency-Key *	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 | 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: 400, 401, 403, 409, 413, 415, 422, 429, 503. See policies for the error envelope.

GET /feeds/{feed}

Token ability: feeds:read

Parameters

Name	In	Type	Description
feed *	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: 401, 403, 404, 429, 503. See policies for the error envelope.

PATCH /feeds/{feed}

Token ability: feeds:write

Parameters

Name	In	Type	Description
feed *	path	integer
Idempotency-Key *	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: 400, 401, 403, 404, 409, 413, 415, 422, 429, 503. See policies for the error envelope.

DELETE /feeds/{feed}

Token ability: feeds:write

Parameters

Name	In	Type	Description
feed *	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: 400, 401, 403, 404, 409, 413, 415, 422, 429, 503. 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 *	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: 401, 403, 404, 422, 429, 503. 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: 401, 403, 404, 422, 429, 503. See policies for the error envelope.

POST /posts

Token ability: posts:write

Parameters

Name	In	Type	Description
Idempotency-Key *	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 | null
body	string | null
author	string | null
tag_ids	array<integer> | null
image_url	string | null
status *	"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: 400, 401, 403, 404, 409, 413, 415, 422, 429, 503. See policies for the error envelope.

GET /posts/{post}

Token ability: posts:read

Parameters

Name	In	Type	Description
post *	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: 401, 403, 404, 429, 503. See policies for the error envelope.

PATCH /posts/{post}

Token ability: posts:write

Parameters

Name	In	Type	Description
post *	path	integer
Idempotency-Key *	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: 400, 401, 403, 404, 409, 413, 415, 422, 429, 503. See policies for the error envelope.

DELETE /posts/{post}

Token ability: posts:write

Parameters

Name	In	Type	Description
post *	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: 400, 401, 403, 404, 409, 413, 415, 422, 429, 503. 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: 401, 403, 422, 429, 503. 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: 401, 403, 422, 429, 503. See policies for the error envelope.

GET /publishers/{publisher}

Token ability: publishers:read

Parameters

Name	In	Type	Description
publisher *	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: 401, 403, 404, 429, 503. 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: 401, 403, 422, 429, 503. 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