Aidelly AI Calendar API

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