Aidelly AI Scheduled Posts API
Scheduled posts API, including compose-time auto-recycle (#847) and the self-healing publish audit trail (#852). Public API preview.
Scheduled posts API, including compose-time auto-recycle (#847) and the self-healing publish audit trail (#852). Public API preview.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/aidelly-ai:aidelly-ai-scheduledposts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Aidelly Public Scheduled Posts API
version: 1.1.0
x-versioning-policy: https://www.aidelly.ai/developers/api/deprecation
description: 'Customer-facing API for publishing and scheduling social posts through Aidelly.
All responses use `{ success, data | error, request_id }`.
This API is optimized for single-user project integrations and AI agents:
- deterministic error codes
- required idempotency on writes
- plan-aware rate-limit headers on authenticated responses'
servers:
- url: https://app.aidelly.ai/api/public/v1
security:
- bearerAuth: []
tags:
- name: ScheduledPosts
description: 'Scheduled posts API, including compose-time auto-recycle (#847) and
the self-healing publish audit trail (#852). Public API preview.'
paths:
/scheduled-posts:
get:
tags:
- ScheduledPosts
summary: List scheduled posts for the workspace
description: 'Public API preview. Surfaces every scheduled_post including
compose-time recycle entries (#847) and approval state (#788).'
operationId: listScheduledPosts
parameters:
- $ref: '#/components/parameters/WorkspaceId'
- in: query
name: from
schema:
type: string
format: date-time
- in: query
name: to
schema:
type: string
format: date-time
- in: query
name: status
schema:
type: string
enum:
- scheduled
- pending
- processing
- retry
- completed
- failed
- canceled
- in: query
name: platform
schema:
$ref: '#/components/schemas/Platform'
- in: query
name: limit
description: Page size. Use `cursor` to page beyond this many results.
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- in: query
name: cursor
description: Opaque cursor from a previous response's `next_cursor`. Treat it as opaque; its encoding is not part of the contract. Omit to start at the first page.
schema:
type: string
maxLength: 512
responses:
'200':
description: Scheduled post list
content:
application/json:
schema:
$ref: '#/components/schemas/PostListEnvelope'
x-tool-name: aidelly_list_scheduled_posts
x-scope: posts:read
x-tool-description: List workspace scheduled posts with from/to timestamps, status, platform, and cursor pagination (maximum 100 per page). Returns items with scheduled_at and approval_status; an empty items array means no matching posts. Approval state is separate from publishing status.
security:
- bearerAuth: []
- oauth2:
- posts:read
post:
tags:
- ScheduledPosts
summary: Schedule a post with optional auto-recycle entries
description: 'Public API preview. Accepts `recycle` array (up to 3 reposts and 3
reshares) for compose-time auto-recycle (#847). When the workspace
has Team Approvals on and the caller is a member, the post lands
in `approval_status = pending` instead of publishing immediately.
Bare media-library UUIDs in `payload.media` are resolved within the
selected workspace before the post is stored.'
operationId: createScheduledPost
parameters:
- $ref: '#/components/parameters/WorkspaceId'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateScheduledPostRequest'
responses:
'201':
description: Scheduled post created
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ScheduledPost'
request_id:
type: string
'400':
$ref: '#/components/responses/BadRequestResponse'
'422':
$ref: '#/components/responses/UnprocessableResponse'
x-tool-name: aidelly_create_scheduled_post
x-scope: posts:write
x-tool-description: 'Schedule a post for a future time, with optional auto-recycle entries (up to 3 reposts and 3 reshares). Scheduled posts publish automatically at their time; when Team Approvals is on, posts submitted by members are held as pending until approved. LinkedIn document posts attach one PDF (≤100 MB, ≤300 pages) as media[].type = "document"; documents are rejected on every other platform. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- posts:write
/scheduled-posts/{id}:
get:
tags:
- ScheduledPosts
summary: Get one scheduled post
operationId: getScheduledPost
parameters:
- $ref: '#/components/parameters/WorkspaceId'
- in: path
name: id
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Scheduled post detail
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
$ref: '#/components/schemas/ScheduledPost'
request_id:
type: string
'404':
$ref: '#/components/responses/NotFoundResponse'
x-tool-name: aidelly_get_scheduled_post
x-scope: posts:read
x-tool-description: Read one scheduled post, including its recycle plan and approval state. Read-only.
security:
- bearerAuth: []
- oauth2:
- posts:read
description: Read one scheduled post, including its recycle plan and approval state. Read-only.
patch:
tags:
- ScheduledPosts
summary: Update a scheduled post (caption, schedule, recycle plan)
operationId: updateScheduledPost
parameters:
- $ref: '#/components/parameters/WorkspaceId'
- $ref: '#/components/parameters/IdempotencyKey'
- in: path
name: id
required: true
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateScheduledPostRequest'
responses:
'200':
description: Updated
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EnvelopeBase'
- type: object
properties:
success:
const: true
data:
type: object
properties:
post:
$ref: '#/components/schemas/ScheduledPost'
x-tool-name: aidelly_update_scheduled_post
x-scope: posts:write
x-tool-description: 'Update the caption, schedule, or recycle plan of a scheduled post. Overwrites the supplied fields; a new time changes when the post publishes. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- posts:write
description: 'Update the caption, schedule, or recycle plan of a scheduled post. Overwrites the supplied fields; a new time changes when the post publishes. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
delete:
tags:
- ScheduledPosts
summary: Cancel a scheduled post
operationId: cancelScheduledPost
parameters:
- $ref: '#/components/parameters/WorkspaceId'
- $ref: '#/components/parameters/IdempotencyKey'
- in: path
name: id
required: true
schema:
type: string
format: uuid
responses:
'200':
description: Cancelled
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/EnvelopeBase'
- type: object
properties:
success:
const: true
data:
$ref: '#/components/schemas/ScheduledPostDeleteResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
x-tool-name: aidelly_cancel_scheduled_post
x-scope: posts:write
x-tool-description: 'Cancel a scheduled calendar post in the workspace and its pending auto-recycle entries (reposts and reshares waiting on it). Statuses become canceled and the records are kept. Requires a workspace-scoped key or workspace_id. aidelly_cancel_post cancels only the single post. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- posts:write
description: 'Cancel a scheduled calendar post in the workspace and its pending auto-recycle entries (reposts and reshares waiting on it). Statuses become canceled and the records are kept. Requires a workspace-scoped key or workspace_id. aidelly_cancel_post cancels only the single post. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
components:
schemas:
CreateScheduledPostRequest:
type: object
required:
- platform
- scheduled_at
- payload
properties:
platform:
type: string
account_id:
type: string
description: A provider account ID from `/accounts`, or a social connection UUID selector.
scheduled_at:
type: string
format: date-time
timezone:
type: string
default: UTC
payload:
type: object
description: 'Post content. `payload.media` accepts URL objects, objects with `media_id`, or bare media-library UUID strings owned by the selected workspace.
`media[].type` accepts `image`, `video`, `gif`, or `document`, and is resolved from the media-library row when omitted (`application/pdf` → `document`).
LinkedIn document posts attach one PDF (≤100 MB, ≤300 pages) as `media[].type = "document"`; documents on any other platform are rejected with `422`.
'
additionalProperties: true
recycle:
type: array
maxItems: 6
items:
$ref: '#/components/schemas/RecycleEntry'
content_campaign_id:
type: string
format: uuid
nullable: true
ScheduledPostDeleteResponse:
type: object
properties:
id:
type: string
format: uuid
status:
type: string
enum:
- canceled
PublicPost:
type: object
properties:
id:
type: string
format: uuid
platform:
$ref: '#/components/schemas/Platform'
account_id:
type: string
nullable: true
status:
$ref: '#/components/schemas/PostStatus'
scheduled_at:
type: string
format: date-time
timezone:
type: string
provider_post_id:
type: string
nullable: true
error_code:
type: string
nullable: true
error:
type: string
nullable: true
approval_status:
type: string
enum:
- pending
- approved
- rejected
nullable: true
description: Set when Team Approvals holds or records a decision on the post.
submitted_by_user_id:
type: string
format: uuid
nullable: true
submitted_for_approval_at:
type: string
format: date-time
nullable: true
rejection_reason:
type: string
nullable: true
description: The reviewer's reason when the post was rejected or sent back for changes. When the API key's user has the client role in the post's workspace, a reason written by a team reviewer (owner, admin or member) is returned as null; a reason from a client reviewer or a client review link is always returned.
content:
type: object
additionalProperties: true
metadata:
type: object
additionalProperties: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
ScheduledPostApprovalStatus:
type: string
enum:
- pending
- approved
- rejected
UpdateScheduledPostRequest:
type: object
properties:
scheduled_at:
type: string
format: date-time
timezone:
type: string
payload:
type: object
description: Replacement post content. `payload.media` accepts URL objects, objects with `media_id`, or bare media-library UUID strings owned by the selected workspace.
additionalProperties: true
recycle:
type: array
maxItems: 6
items:
$ref: '#/components/schemas/RecycleEntry'
PostListEnvelope:
allOf:
- $ref: '#/components/schemas/EnvelopeBase'
- type: object
properties:
success:
const: true
data:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/PublicPost'
count:
type: integer
description: Number of items on this page.
has_more:
type: boolean
description: True when further pages are available.
next_cursor:
type: string
nullable: true
description: Pass as `cursor` to fetch the next page. Null on the last page.
RecycleEntry:
type: object
required:
- kind
- offset_seconds
properties:
kind:
type: string
enum:
- repost
- reshare
offset_seconds:
type: integer
minimum: 3600
maximum: 31536000
description: Seconds after the source publishes when this recycle fires.
EnvelopeBase:
type: object
required:
- success
- request_id
properties:
success:
type: boolean
request_id:
type: string
format: uuid
Platform:
type: string
enum:
- facebook
- instagram
- linkedin
- twitter
- bluesky
- threads
- pinterest
- youtube
- tiktok
- google_business
- mastodon
description: 'Supported platform identifier. `twitter` and `x` map to the same surface;
responses always normalize to `twitter`. `google_business` posts target
a single Google Business Profile location identified by
`platform_specific.locationName`. `mastodon` accounts are per-instance —
the connected account carries its own `instance_url`.
'
example: linkedin
ErrorEnvelope:
allOf:
- $ref: '#/components/schemas/EnvelopeBase'
- type: object
required:
- error
properties:
success:
const: false
error:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
details:
description: Machine-readable error details object. Plan/feature gates use PlanLimitErrorDetails.
oneOf:
- $ref: '#/components/schemas/PlanLimitErrorDetails'
- type: object
additionalProperties: true
PostStatus:
type: string
enum:
- scheduled
- pending
- processing
- retry
- completed
- failed
- canceled
example: scheduled
ScheduledPost:
type: object
required:
- id
- platform
- scheduled_at
- timezone
- status
properties:
id:
type: string
format: uuid
platform:
type: string
account_id:
type: string
nullable: true
scheduled_at:
type: string
format: date-time
timezone:
type: string
status:
type: string
enum:
- scheduled
- publishing
- published
- failed
- cancelled
- pending_approval
approval_status:
$ref: '#/components/schemas/ScheduledPostApprovalStatus'
source_post_id:
type: string
format: uuid
nullable: true
description: Set when this row is a recycle child of another post.
recycle:
type: array
maxItems: 6
items:
$ref: '#/components/schemas/RecycleEntry'
content_campaign_id:
type: string
format: uuid
nullable: true
payload:
type: object
additionalProperties: true
created_at:
type: string
format: date-time
PlanLimitErrorDetails:
type: object
additionalProperties: false
required:
- limit_key
- plan_tier
- current_usage
- limit
- reset_at
- recommended_plan
- upgrade_url
properties:
limit_key:
type: string
example: automations.active
plan_tier:
type: string
example: launch
current_usage:
type: integer
nullable: true
example: 5
limit:
type: integer
nullable: true
example: 5
reset_at:
type: string
format: date-time
nullable: true
example: 2026-03-31 23:59:59+00:00
recommended_plan:
type: string
nullable: true
example: scale
upgrade_url:
type: string
format: uri
example: https://app.aidelly.ai/account/billing
responses:
UnprocessableResponse:
description: Content validation or publishing failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
contentValidation:
value:
success: false
error:
code: CONTENT_VALIDATION_FAILED
message: Post exceeds Threads's 500-character limit.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
publishFailure:
value:
success: false
error:
code: PUBLIC_API_PUBLISH_FAILED
message: Post publishing failed.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
BadRequestResponse:
description: Request validation failed (body, missing Idempotency-Key, or invalid Idempotency-Key)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
examples:
bodyInvalid:
value:
success: false
error:
code: PUBLIC_API_BODY_INVALID
message: Invalid request body.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
idempotencyKeyInvalid:
value:
success: false
error:
code: PUBLIC_API_IDEMPOTENCY_KEY_INVALID
message: 'Idempotency-Key must be 1-255 printable ASCII characters with no spaces (letters, digits, and punctuation such as - _ : . are allowed).'
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
NotFoundResponse:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PUBLIC_API_POST_NOT_FOUND
message: Post not found.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
parameters:
WorkspaceId:
in: header
name: x-aidelly-workspace-id
required: false
schema:
type: string
format: uuid
description: 'Workspace to operate in: the `id` of a workspace returned by aidelly_list_workspaces. Optional for read operations; required when creating content.'
description: Optional workspace scope override for workspace-compatible API keys.
IdempotencyKey:
in: header
name: Idempotency-Key
required: true
schema:
type: string
minLength: 1
maxLength: 255
pattern: ^[\x21-\x7E]{1,255}$
example: order-123:create-post:v1
description: 'Required on all write endpoints. 1-255 printable ASCII characters (0x21-0x7E): letters, digits, and punctuation such as `-`, `_`, `.`, and `:` are allowed; spaces, control characters, and non-ASCII are not. Leading and trailing whitespace is trimmed. An invalid key returns 400 `PUBLIC_API_IDEMPOTENCY_KEY_INVALID`; a missing key returns 400 `PUBLIC_API_IDEMPOTENCY_REQUIRED`. Keys are scoped to the API key, method, and path.'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
oauth2:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://app.aidelly.ai/api/mcp/oauth/authorize
tokenUrl: https://app.aidelly.ai/api/mcp/oauth/token
refreshUrl: https://app.aidelly.ai/api/mcp/oauth/token
scopes:
posts:write: Create and modify posts
posts:read: Read access to posts
photos:write: Create and modify photos
media:write: Create and modify media
connections:read: Read access to connections
webhooks:manage: Manage webhooks
approvals:read: Read access to approvals
approvals:write: Create and modify approvals
inbox:read: Read access to inbox
inbox:write: Create and modify inbox
automations:read: Read access to automations
automations:write: Create and modify automations
queues:read: Read access to queues
queues:write: Create and modify queues
destination-presets:read: Read access to destination-presets
destination-presets:write: Create and modify destination-presets
calendar:read: Read access to calendar
calendar:write: Create and modify calendar
analytics:read: Read access to analytics
analytics:write: Create and modify analytics
brand:read: Read access to brand
brand:write: Create and modify brand
workspaces:read: Read access to workspaces
workspaces:write: Create and modify workspaces
team:read: Read access to team
team:write: Create and modify team
repurpose:read: Read access to repurpose
repurpose:write: Create and modify repurpose
ideas:read: Read access to ideas
ideas:write: Create and modify ideas
links:read: Read access to links
links:write: Create and modify links
connect_links:read: Read access to connect_links
connect_links:write: Create and modify connect_links
bio:read: Read access to bio
bio:write: Create and modify bio
image_editor:read: Read access to image_editor
image_editor:write: Create and modify image_editor
viral_trends:read: Read access to viral_trends
creators:read: Read access to creators
creators:write: Create and modify creators
competitors:read: Read access to competitors
competitors:write: Create and modify competitors
reports:read: Read access to reports
reports:write: Create and modify reports
tasks:read: Read access to tasks
tasks:write: Create and modify tasks
white-label:read: Read access to white-label
white-label:write: Create and modify white-label
drafts:read: Read access to drafts
drafts:write: Create and modify drafts
activity:read: Read access to activity
credits:read: Read access to credits
comments:read: Read access to comments
comments:write: Create and modify comments
prompts:read: Read access to prompts
prompts:write: Create and modify prompts
externalDocs:
description: Aidelly developer documentation and API lifecycle policy
url: https://www.aidelly.ai/docs