Aidelly AI Calendar API
The Calendar API from Aidelly AI — 5 operation(s) for calendar.
The Calendar API from Aidelly AI — 5 operation(s) for calendar.
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-calendar-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 Calendar 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: Calendar
paths:
/calendar/events:
get:
tags:
- Calendar
summary: List calendar events
operationId: listCalendarEvents
responses:
'200':
$ref: '#/components/responses/UsageEnvelopeResponse'
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/InternalErrorResponse'
x-tool-name: aidelly_get_calendar_events
x-scope: calendar:read
x-tool-description: List content calendar events for the selected workspace, including timing, status, and content details. Use returned cursors to read additional pages. This only reads the calendar.
parameters:
- 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. When both `cursor` and offset-style parameters are sent, the cursor wins.
schema:
type: string
maxLength: 512
security:
- bearerAuth: []
- oauth2:
- calendar:read
description: List content calendar events for the selected workspace, including timing, status, and content details. Use returned cursors to read additional pages. This only reads the calendar.
/calendar/events/{id}:
patch:
tags:
- Calendar
summary: Update calendar event
operationId: updateCalendarEvent
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
$ref: '#/components/responses/UsageEnvelopeResponse'
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/InternalErrorResponse'
x-tool-name: aidelly_update_calendar_event
x-tool-aliases:
- aidelly_patch_calendar_events_id
x-scope: calendar:write
x-tool-description: 'Update an existing calendar event by id. Supply changed fields in body, such as scheduled_at, timezone, event_title, or scheduled_content_text. Overwrites stored event fields and can change when the content publishes; returns the updated event. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- calendar:write
description: 'Update an existing calendar event by id. Supply changed fields in body, such as scheduled_at, timezone, event_title, or scheduled_content_text. Overwrites stored event fields and can change when the content publishes; returns the updated event. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
delete:
tags:
- Calendar
summary: Delete calendar event
operationId: deleteCalendarEvent
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'200':
$ref: '#/components/responses/UsageEnvelopeResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/InternalErrorResponse'
x-tool-name: aidelly_delete_calendar_event
x-tool-aliases:
- aidelly_delete_calendar_events_id
x-scope: calendar:write
x-tool-description: 'Delete a calendar event by id from the selected workspace. Removes the stored event, or cancels the post when the calendar uses scheduled posts as its backing store. Returns the deletion result. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- calendar:write
description: 'Delete a calendar event by id from the selected workspace. Removes the stored event, or cancels the post when the calendar uses scheduled posts as its backing store. Returns the deletion result. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
/calendar/share-links/{id}:
delete:
tags:
- Calendar
summary: Delete a calendar share link
description: 'Permanently deletes a calendar share link. The public
`/calendar/share/` URL stops resolving immediately.
The in-app surface only disables a link (`is_enabled = false`); this is
the hard delete. Unknown ids and ids belonging to another workspace both
return 404 — there is no distinct code for "exists but not yours".'
operationId: deleteCalendarShareLink
parameters:
- in: path
name: id
required: true
schema:
type: string
format: uuid
- $ref: '#/components/parameters/WorkspaceId'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'200':
description: Calendar share link deleted
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
deleted:
type: boolean
share_link_id:
type: string
format: uuid
request_id:
type: string
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'409':
$ref: '#/components/responses/ConflictResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/InternalErrorResponse'
x-tool-name: aidelly_delete_calendar_share_link
x-scope: calendar:write
x-tool-description: 'Permanently delete a calendar share link so its public /calendar/share/<token> URL stops working. Irreversible; disabling the link in the Aidelly app is the reversible alternative. Returns 404 for unknown ids and for links in another workspace alike. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- calendar:write
/calendar/bulk-fill:
post:
tags:
- Calendar
summary: Create async bulk calendar fill job
operationId: createBulkFillJob
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
posts:
type: array
minItems: 1
maxItems: 200
items:
type: object
properties:
clientId:
type: string
description: Unique client-side ID for deduping retries
platform:
type: string
description: Social platform
accountId:
type: string
nullable: true
description: Platform account ID
scheduledAt:
type: string
format: date-time
description: ISO 8601 datetime with offset
timezone:
type: string
default: UTC
title:
type: string
maxLength: 300
caption:
type: string
minLength: 1
maxLength: 10000
hashtags:
type: array
maxItems: 30
items:
type: string
mentions:
type: array
maxItems: 30
items:
type: string
mediaUrl:
type: string
maxLength: 2000
nullable: true
contentType:
type: string
maxLength: 40
firstComment:
type: string
maxLength: 2200
nullable: true
dmAutomation:
type: object
nullable: true
properties:
keyword:
type: string
message:
type: string
link:
type: string
commentReply:
type: string
responses:
'202':
$ref: '#/components/responses/UsageEnvelopeResponse'
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/InternalErrorResponse'
x-tool-name: aidelly_create_bulk_fill_job
x-scope: calendar:write
x-tool-description: 'Create an asynchronous job to schedule 1-200 supplied social posts in the selected workspace. Each post specifies its platform, caption, and scheduledAt time with an offset, plus its destination and optional media. This creates publishable scheduled content subject to workspace approval rules. Returns a job id; aidelly_get_bulk_fill_job reports progress and completion. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
security:
- bearerAuth: []
- oauth2:
- calendar:write
description: 'Create an asynchronous job to schedule 1-200 supplied social posts in the selected workspace. Each post specifies its platform, caption, and scheduledAt time with an offset, plus its destination and optional media. This creates publishable scheduled content subject to workspace approval rules. Returns a job id; aidelly_get_bulk_fill_job reports progress and completion. Retry-safe: a repeat call with the same idempotency_key returns the original result.'
/calendar/bulk-fill/{jobId}:
get:
tags:
- Calendar
summary: Get bulk fill job status
operationId: getBulkFillJob
parameters:
- in: path
name: jobId
required: true
schema:
type: string
format: uuid
responses:
'200':
$ref: '#/components/responses/UsageEnvelopeResponse'
'400':
$ref: '#/components/responses/BadRequestResponse'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'429':
$ref: '#/components/responses/RateLimitedResponse'
'500':
$ref: '#/components/responses/InternalErrorResponse'
x-tool-name: aidelly_get_bulk_fill_job
x-scope: calendar:read
x-tool-description: Read the status of a previously created bulk calendar fill job by jobId. Returns job progress or completion status; a successful job creation response alone does not mean all posts were scheduled. Does not create or retry posts.
security:
- bearerAuth: []
- oauth2:
- calendar:read
description: Read the status of a previously created bulk calendar fill job by jobId. Returns job progress or completion status; a successful job creation response alone does not mean all posts were scheduled. Does not create or retry posts.
components:
headers:
XRateLimitLimit:
description: Maximum requests allowed in the current window.
schema:
type: integer
example: 120
XRateLimitPlan:
description: Resolved plan tier for rate limiting.
schema:
type: string
enum:
- launch
- scale
- agency
- fallback
example: scale
XRateLimitResetEpoch:
description: Unix epoch seconds for current window reset.
schema:
type: integer
example: 1771353600
RateLimitLimit:
description: RFC 9333 maximum requests allowed in the current window.
schema:
type: integer
minimum: 0
example: 120
XRateLimitWindowSeconds:
description: Rate limit window duration in seconds.
schema:
type: integer
example: 60
RateLimitPolicy:
description: Quota policy extension using limit and window parameters.
schema:
type: string
example: 120;w=60
RateLimitRemaining:
description: RFC 9333 requests remaining in the current window.
schema:
type: integer
minimum: 0
example: 118
XRateLimitReset:
description: ISO timestamp for current window reset.
schema:
type: string
format: date-time
example: 2026-02-17 18:40:00+00:00
XRateLimitRemaining:
description: Remaining requests available in the current window.
schema:
type: integer
example: 118
RateLimitReset:
description: RFC 9333 seconds until the current window resets.
schema:
type: integer
minimum: 1
example: 42
RetryAfter:
description: Seconds to wait before retrying after a `429`.
schema:
type: integer
minimum: 1
example: 17
schemas:
EnvelopeBase:
type: object
required:
- success
- request_id
properties:
success:
type: boolean
request_id:
type: string
format: uuid
UsageEnvelope:
allOf:
- $ref: '#/components/schemas/EnvelopeBase'
- type: object
properties:
success:
const: true
data:
type: object
additionalProperties: true
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
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
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.'
responses:
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
UnauthorizedResponse:
description: API key missing, invalid, or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PUBLIC_API_AUTH_REQUIRED
message: A Bearer API key is required.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
ForbiddenResponse:
description: API key scope or context restriction failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PUBLIC_API_SCOPE_FORBIDDEN
message: The API key does not include required scopes.
details:
missing_scopes:
- posts:write
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
ConflictResponse:
description: Idempotency conflict or state conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PUBLIC_API_IDEMPOTENCY_CONFLICT
message: Idempotency-Key was already used with a different request body.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
InternalErrorResponse:
description: Unexpected server-side failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PUBLIC_API_POST_CREATE_FAILED
message: Unable to create scheduled post.
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
UsageEnvelopeResponse:
description: Generic successful response envelope
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/XRateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/XRateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/XRateLimitReset'
X-RateLimit-Reset-Epoch:
$ref: '#/components/headers/XRateLimitResetEpoch'
X-RateLimit-Window-Seconds:
$ref: '#/components/headers/XRateLimitWindowSeconds'
X-RateLimit-Plan:
$ref: '#/components/headers/XRateLimitPlan'
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
RateLimit-Policy:
$ref: '#/components/headers/RateLimitPolicy'
content:
application/json:
schema:
$ref: '#/components/schemas/UsageEnvelope'
RateLimitedResponse:
description: API key exceeded allowed request throughput
headers:
RateLimit-Limit:
$ref: '#/components/headers/RateLimitLimit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimitRemaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimitReset'
RateLimit-Policy:
$ref: '#/components/headers/RateLimitPolicy'
X-RateLimit-Limit:
$ref: '#/components/headers/XRateLimitLimit'
X-RateLimit-Remaining:
$ref: '#/components/headers/XRateLimitRemaining'
X-RateLimit-Reset:
$ref: '#/components/headers/XRateLimitReset'
X-RateLimit-Reset-Epoch:
$ref: '#/components/headers/XRateLimitResetEpoch'
X-RateLimit-Window-Seconds:
$ref: '#/components/headers/XRateLimitWindowSeconds'
X-RateLimit-Plan:
$ref: '#/components/headers/XRateLimitPlan'
Retry-After:
$ref: '#/components/headers/RetryAfter'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
example:
success: false
error:
code: PUBLIC_API_RATE_LIMITED
message: Rate limit exceeded.
request_id: e2f4f215-183a-47f7-bd4f-29a9380d9528
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