API Reference

Explore the REST API of your Genfeed instance with the interactive documentation below. Example requests use the default local address http://localhost:3010/v1; substitute your own API URL if you run behind a domain (see Reverse Proxy and HTTPS).

Your instance serves its own OpenAPI document at http://localhost:3010/v1/openapi.json. The viewer at the bottom of this page renders the published spec for the current release as read-only documentation: it describes the routes your instance serves, and “Try it out” is disabled so nothing is sent to any server from this page.

Scheduling

Scheduling uses release groups: one shared piece of content with one or more channel targets. Send a bearer API key with the appropriate posts scope. The canonical release identifier returned by any surface can be used by REST, MCP, or the CLI.

Release lifecycle

Method	Route	Purpose
`GET`	`/v1/post-groups`	List release groups. Supports release-window, brand, status, platform, credential, execution-state, content-type, source, search, sort, and pagination filters.
`POST`	`/v1/post-groups`	Create a draft or scheduled multi-channel release. An optional `Idempotency-Key` header makes retries safe.
`POST`	`/v1/post-groups/from-post`	Ensure an existing post has a canonical release group.
`GET`	`/v1/post-groups/{id}`	Read the current release and per-target status.
`PATCH`	`/v1/post-groups/{id}`	Edit release fields, reschedule with `scheduledDate`, or apply a lifecycle `action`.
`PATCH`	`/v1/post-groups/{id}/targets/{targetId}`	Edit one channel target or apply a target scheduling/publish action.
`POST`	`/v1/post-groups/recurrence/preview`	Preview a recurrence rule without creating a release.
`PATCH`	`/v1/post-groups/{id}/series/future`	Edit future occurrences in a recurring series.

PATCH /v1/post-groups/{id} accepts lifecycle actions cancel, pause, resume, and publish-now. Recurring-series actions and calendar moves use the same route. To reschedule without changing content, send the request field scheduledDate; serialized responses expose the resulting timestamp as scheduledAt.


curl -X PATCH http://localhost:3010/v1/post-groups/RELEASE_ID \
  -H "Authorization: Bearer $GENFEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scheduledDate":"2026-09-01T10:00:00.000Z"}'

Cancel the same release with the canonical lifecycle action:


curl -X PATCH http://localhost:3010/v1/post-groups/RELEASE_ID \
  -H "Authorization: Bearer $GENFEED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"cancel"}'

Calendar, channel capabilities, and readiness

Method	Route	Purpose
`GET`	`/v1/schedules/calendar`	Read scheduled entries for an optional `start` and `end` range.
`POST`	`/v1/schedules/bulk`	Schedule multiple content items.
`POST`	`/v1/schedules/optimal`	Best posting windows for a platform and timezone: learned from your own measured posts once there are enough, otherwise labelled default times. No model call.
`GET`	`/v1/schedules/channel-capabilities`	List channel publishing contracts. `includeHidden` and `includePlanned` are optional boolean query parameters.
`GET`	`/v1/schedules/channel-capabilities/{platform}`	Read one platform’s limits, media rules, publish modes, settings, and support status.
`POST`	`/v1/schedules/channel-capabilities/validate`	Validate a proposed target without creating or updating a release.
`GET`	`/v1/credentials/brand/{brandId}/publishing-readiness`	List the brand’s connected channels with credential ID, provider, `canSchedule`, readiness state, required action, and safe diagnostics.

Check publishing readiness before creating a release. A channel with canSchedule: false must be repaired before it can be used as a target; requiredAction and diagnostics explain the next step without returning credential secrets.

Loading API Documentation…