> ## Documentation Index
> Fetch the complete documentation index at: https://docs.smartlyq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reschedule a booking

> Moves a confirmed booking to a new time, keeping its length and its guests and never charging again. The calendar checks availability, makes the new meeting link, tells the attendee and updates connected calendars. The booking keeps its `id` but gets a new `uid`, and `booking.rescheduled` fires. Answers 422 when the booking cannot be moved as it stands (it is cancelled, waiting for approval, not confirmed, or an appointment copied from a connected calendar) or when `start` is missing, not ISO 8601 or already past; 409 when the calendar refuses the move: the time is not available (pick another from the slots endpoint), the booking is still waiting for its payment, or the booking page has shared seats or now requires an answer this booking does not have; 403 when the key's user is not the host of the booking or on its team; 429 after too many changes in a short time; 502 when the calendar did not answer in time, in which case the booking may or may not have moved, so read it before trying again. Requires scope `calendar:write`.



## OpenAPI

````yaml /openapi.json post /calendar/bookings/{id}/reschedule
openapi: 3.1.0
info:
  title: SmartlyQ API
  version: 1.0.0
  description: >
    # SmartlyQ API


    REST API for the SmartlyQ platform: generate content, manage social posts,
    chatbots, media, and more.


    ## Quick Start


    1. Get an API key from
    [app.smartlyq.com/next/developer](https://app.smartlyq.com/next/developer).

    2. Send your first request:


    ```bash

    curl -H "Authorization: Bearer YOUR_API_KEY" https://api.smartlyq.com/v1/me

    ```


    ## Idempotency


    Every `POST`/`PUT`/`PATCH` endpoint supports safe retries: send an
    `X-Idempotency-Key` header (any unique string, e.g. a UUID). If the same key
    is replayed within 24 hours with the same request, you get the original
    response back - the action never runs twice, and you are never
    double-billed. Reusing a key with a *different* body or endpoint returns
    `409 IDEMPOTENCY_CONFLICT`.


    ```bash

    curl -X POST https://api.smartlyq.com/v1/social/posts/schedule \
      -H "Authorization: Bearer sqk_live_xxxx" \
      -H "X-Idempotency-Key: 5f0c9a4e-2b7d-4d1a-9c58-e2ff10c3a771" \
      -d '{...}'
    ```


    ## Authentication


    All requests (except health/docs) require a **Bearer token**. Use your API
    key as the token:


    - **Key types:** `sqk_live_*` (live) or `sqk_test_*` (test/sandbox).

    - **Header:** `Authorization: Bearer sqk_live_xxxx` or `Authorization:
    Bearer sqk_test_xxxx`.


    | Scope | Description |

    |-------|-------------|

    | `articles:read` | List and get articles |

    | `articles:write` | Generate, delete articles |

    | `images:read` | List and get images |

    | `images:write` | Generate, delete images |

    | `videos:read` | List and get videos |

    | `videos:write` | Generate, delete videos |

    | `presentations:read` | List and get presentations |

    | `presentations:write` | Generate presentations |

    | `social:read` | Accounts (health, follower stats, platform lookups),
    posts, queues, comments, DMs, reviews, pre-flight validation, Reddit
    research |

    | `social:write` | Create/schedule/bulk posts, recycling, unpublish, queues,
    reply to comments/DMs/reviews, account rename/move, account groups |

    | `audio:read` | Get audio resources |

    | `audio:write` | Text-to-speech, speech-to-text |

    | `urls:read` | List and get short URLs and stats |

    | `urls:write` | Shorten, delete URLs |

    | `captain:use` | AI Captain messages and conversations |

    | `chatbot:use` | Chatbots, train, messages, conversations |

    | `media:read` | List and get media |

    | `media:write` | Upload, delete media |

    | `analytics:read` | Overview, post and account analytics, derived insights
    (best-time, decay, frequency), inbox analytics |

    | `jobs:read` | List and get async jobs, cancel |

    | `seo:read` | Keyword research, SERP, rank tracking, competitors,
    backlinks, on-page audits |

    | `contacts:read` | List and get CRM contacts, tags, notes; list automations
    and their runs |

    | `contacts:write` | Create/update/delete contacts (single or bulk); tags
    and notes; enroll in, activate and trigger automations |

    | `companies:read` | List and get companies, their contacts, deals and value
    rollup |

    | `companies:write` | Create/update/delete companies; link and unlink
    contacts |

    | `tasks:read` | List and get CRM tasks and activities |

    | `tasks:write` | Create/update/delete tasks, log time; fires task_created
    and task_completed |

    | `calendar:read` | List booking pages and the open slots on them |

    | `calendar:write` | Take and cancel bookings |

    | `opportunities:read` | List pipelines and deals/opportunities |

    | `opportunities:write` | Create/update deals, move stages, set status |

    | `webhooks:read` | List webhooks and delivery logs |

    | `webhooks:write` | Create, update, test and delete webhooks |

    | `logs:read` | Read your API request + webhook delivery logs |

    | `workspaces:read` | List and get sub-account workspaces |

    | `workspaces:write` | Create, disable SaaS, and delete sub-account
    workspaces |

    | `workspaces:bulk` | Apply pause / resume / disable-SaaS to many
    sub-accounts at once (high-trust; requires an active SaaS plan) |


    ## Billing & Credits


    - **Prepaid wallet:** API usage is deducted from your Developer API wallet
    (credits in SQC).

    - **Pricing:** See the [pricing table](https://smartlyq.com/pricing) and
    in-app Developer dashboard for per-operation costs.

    - **How it works:** Each billable request (e.g. generate, post, chatbot
    message) consumes credits; response may include `usage` with `cost` and
    `balance_remaining`.

    - **Top up:** Add credits via
    [app.smartlyq.com/next/developer](https://app.smartlyq.com/next/developer)
    (wallet / top-up).


    ## Rate Limiting


    Limits apply per workspace: every API key in a workspace, including the keys
    MCP connections create, shares one allowance of 60, 600 or 1,200 requests
    per minute depending on the connected social accounts, and analytics reads
    also have a per-second ceiling. Test keys have a separate allowance of the
    same size. Details: [Rate limiting
    guide](https://docs.smartlyq.com/guides/rate-limiting).


    Response headers:


    | Header | Description |

    |--------|-------------|

    | `X-RateLimit-Limit` | Max requests per window |

    | `X-RateLimit-Remaining` | Remaining in current window |

    | `X-RateLimit-Reset` | Unix timestamp when the window resets |


    When exceeded: HTTP `429` with `Retry-After` header.


    ## Errors


    Errors are JSON with a consistent shape:


    ```json

    {
      "success": false,
      "error": {
        "code": "ERROR_CODE",
        "message": "Human-readable message",
        "details": {}
      },
      "meta": { "request_id": "...", "timestamp": "..." }
    }

    ```


    | HTTP | Code | Meaning |

    |-----|------|---------|

    | 400 | `BAD_REQUEST` | Malformed or invalid request |

    | 401 | `UNAUTHORIZED` | Missing or invalid API key |

    | 402 | `INSUFFICIENT_BALANCE` | Not enough credits |

    | 403 | `FORBIDDEN` | Valid key but insufficient scope or access |

    | 404 | `RESOURCE_NOT_FOUND` | Resource does not exist |

    | 409 | `CONFLICT` | Conflict (e.g. duplicate idempotency) |

    | 422 | `VALIDATION_ERROR` | Validation failed (fields in details) |

    | 429 | `RATE_LIMIT_EXCEEDED` | Too many requests |

    | 500 | `INTERNAL_ERROR` | Server error |


    ## Async Jobs & Polling


    Some operations (e.g. article or video generation) return **HTTP 202
    Accepted** with a `job_id`. Poll for status:


    - **Poll:** `GET /jobs/{job_id}` until `status` is `completed`, `failed`, or
    `cancelled`.

    - Response includes `result` or `error` when finished.


    ## Webhooks


    Configure webhook URLs in the Developer dashboard. We send HTTP POST to your
    URL with a signed payload.


    - **Verification:** Validate signature using your webhook secret (see
    dashboard).

    - **Events:** 25 events across posting, accounts, inbox, jobs, billing, and
    CRM - e.g. `post.published`, `comment.received`, `contact.created`. Full
    catalog with payload schemas: the `webhooks` object in this spec and the
    [Webhooks guide](https://docs.smartlyq.com/guides/webhooks).


    ## Idempotency


    For POST/PUT/PATCH, send **`X-Idempotency-Key`** (unique value per logical
    operation). Within 24 hours, the same key returns the same response without
    re-executing.


    ## Pagination


    - **Offset:** `page` (1-based) and `per_page` (default 20, max 100).

    - Response includes `pagination` with `page`, `per_page`, `total`,
    `total_pages`.


    ## Versioning


    Current version is **v1**. Base path: `https://api.smartlyq.com/v1`. Future
    versions will use new path prefixes (e.g. `/v2/`).
  contact:
    name: SmartlyQ Support
    url: https://smartlyq.com
    email: support@smartlyq.com
  license:
    name: Proprietary
    url: https://smartlyq.com/terms
servers:
  - url: https://api.smartlyq.com/v1
    description: Production
security:
  - BearerAuth: []
tags:
  - name: CRM Contacts
    description: 'CRM contacts: create, update, upsert, tags and notes'
  - name: CRM Custom Fields
    description: Custom field (custom attribute) definitions
  - name: CRM Opportunities
    description: Sales pipelines and deals/opportunities
  - name: CRM Companies
    description: Companies / organisations, and the contacts linked to them.
  - name: CRM Tasks
    description: Tasks and activities, with the automation events they fire.
  - name: CRM Tags
    description: The workspace's contact tag vocabulary.
  - name: Calendar
    description: Booking pages, open slots, and taking or cancelling bookings.
  - name: Workspaces
    description: Create sub-account workspaces
  - name: Articles
    description: Long-form article generation and management
  - name: Images
    description: AI image generation and listing
  - name: Videos
    description: AI video generation and listing
  - name: Social
    description: Social accounts and post scheduling
  - name: Content
    description: Content rewriting
  - name: Audio
    description: Text-to-speech and speech-to-text
  - name: URLs
    description: URL shortening and analytics
  - name: AI Captain
    description: AI Captain conversations
  - name: Chatbot
    description: Chatbots, training, and conversations
  - name: Media
    description: Media library and uploads
  - name: Analytics
    description: Analytics overview and reports
  - name: Jobs
    description: Async job status and cancellation
  - name: SEO
    description: >-
      DataForSEO-backed keyword research, SERP, rank tracking, competitors,
      backlinks and on-page audits
  - name: Account
    description: Current user, usage, and balance
  - name: Comments
    description: Comments endpoints
  - name: Direct Messages
    description: Direct Messages endpoints
  - name: Webhooks
    description: Subscribe to event notifications (HMAC-signed deliveries with retries).
  - name: Shorts
    description: 'Magic Shorts: turn long videos into ranked viral clips'
  - name: Edits
    description: >-
      Edit a whole video by API: captions, zooms, b-roll, silence and filler
      removal, clean audio, hook, music. Open the result in the editor or export
      it.
  - name: Presentations
    description: AI presentation (slide deck) generation from a prompt
  - name: Logs
    description: Your own API request and webhook delivery history.
  - name: WhatsApp
    description: WhatsApp Business Cloud messaging, templates and business profile.
  - name: Ads
    description: >-
      Campaigns, ad sets, ads, audiences, pixels, lead forms, creatives,
      connected ad accounts, and diagnostics across Meta, Google, TikTok and
      LinkedIn Ads.
paths:
  /calendar/bookings/{id}/reschedule:
    post:
      tags:
        - Calendar
      summary: Reschedule a booking
      description: >-
        Moves a confirmed booking to a new time, keeping its length and its
        guests and never charging again. The calendar checks availability, makes
        the new meeting link, tells the attendee and updates connected
        calendars. The booking keeps its `id` but gets a new `uid`, and
        `booking.rescheduled` fires. Answers 422 when the booking cannot be
        moved as it stands (it is cancelled, waiting for approval, not
        confirmed, or an appointment copied from a connected calendar) or when
        `start` is missing, not ISO 8601 or already past; 409 when the calendar
        refuses the move: the time is not available (pick another from the slots
        endpoint), the booking is still waiting for its payment, or the booking
        page has shared seats or now requires an answer this booking does not
        have; 403 when the key's user is not the host of the booking or on its
        team; 429 after too many changes in a short time; 502 when the calendar
        did not answer in time, in which case the booking may or may not have
        moved, so read it before trying again. Requires scope `calendar:write`.
      operationId: rescheduleBooking
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Booking id, as it appears on the CRM contact's bookings and in
            booking webhooks.
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                start:
                  type: string
                  description: New ISO 8601 start time, from the slots endpoint.
                reason:
                  type: string
                  description: Shown to the attendee. At most 500 characters.
              required:
                - start
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                  meta:
                    $ref: '#/components/schemas/RequestMeta'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '502':
          description: >-
            The calendar did not answer in time (`UPSTREAM_UNAVAILABLE`). The
            booking may or may not have moved: read it before trying again.
components:
  schemas:
    RequestMeta:
      type: object
      properties:
        request_id:
          type: string
          example: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34
        timestamp:
          type: string
          format: date-time
          example: '2026-07-26T09:41:22Z'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
        meta:
          $ref: '#/components/schemas/RequestMeta'
  responses:
    Forbidden:
      description: Forbidden (scope or access)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: INSUFFICIENT_SCOPE
              message: 'API key lacks required scope: social:write'
              details:
                required_scope: social:write
            meta:
              request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34
              timestamp: '2026-07-26T09:41:22Z'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: RESOURCE_NOT_FOUND
              message: Post not found.
              details: {}
            meta:
              request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34
              timestamp: '2026-07-26T09:41:22Z'
    Conflict:
      description: Conflict (e.g. duplicate idempotency or already-finished job)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: CONFLICT
              message: This resource was modified by another request. Reload and retry.
              details: {}
            meta:
              request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34
              timestamp: '2026-07-26T09:41:22Z'
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: 'Missing required fields: content, platforms.'
              details:
                fields:
                  - content
                  - platforms
            meta:
              request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34
              timestamp: '2026-07-26T09:41:22Z'
    RateLimited:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error:
              code: RATE_LIMIT_EXCEEDED
              message: Rate limit exceeded. Retry after 12 seconds.
              details:
                retry_after: 12
            meta:
              request_id: req_9f3a2b1c-7d4e-4a08-b2c6-5e1f8a9d0c34
              timestamp: '2026-07-26T09:41:22Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sqk_live_* or sqk_test_*
      description: API key from Developer dashboard (Bearer token).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.