openapi: 3.1.0
info:
  title: TheAlterMeAI Post Scheduling API
  version: 1.0.0
  description: |
    Draft and confirm social posts for one workspace. Authenticate with `Authorization: Bearer emk_…`.
    Keys are created under Workspace → API keys. Confirm charges the same Social Vault fee as the app.
    Human-readable guide: https://thealtermeai.com/developers/scheduling
servers:
  - url: https://api.thealtermeai.com
paths:
  /api/v1/scheduling/accounts:
    get:
      summary: List connected accounts
      x-required-scopes: [schedule:read]
      responses:
        "200":
          description: Accounts the key can target
        "401":
          description: Invalid or missing API key
  /api/v1/scheduling/post-groups:
    get:
      summary: List post groups
      x-required-scopes: [schedule:read]
      responses:
        "200":
          description: Draft and scheduled groups
    post:
      summary: Create a draft post group
      x-required-scopes: [schedule:write]
      responses:
        "201":
          description: Draft created. Confirm is a separate call.
  /api/v1/scheduling/post-groups/{id}:
    get:
      summary: Get a post group
      x-required-scopes: [schedule:read]
      responses:
        "200":
          description: Group view, including per-target blockers
        "404":
          description: Not in this workspace
    patch:
      summary: Update a draft
      x-required-scopes: [schedule:write]
      responses:
        "200":
          description: Updated group
    delete:
      summary: Cancel unpublished targets
      x-required-scopes: [schedule:write]
      responses:
        "200":
          description: Cancelled count
  /api/v1/scheduling/post-groups/{id}/confirm:
    post:
      summary: Confirm and charge
      description: Publishes the draft. Returns 422 NOT_READY or 402 INSUFFICIENT_WORK_FUNDS.
      x-required-scopes: [schedule:write]
      responses:
        "200":
          description: Scheduled
        "402":
          description: Insufficient Work Funds
        "403":
          description: Missing scope or feature disabled
        "422":
          description: A target is not ready
  /api/v1/scheduling/post-groups/{id}/reschedule:
    post:
      summary: Move unpublished targets
      description: Body `{ "scheduledFor": "<ISO-8601>", "targetId"?: string }`.
      x-required-scopes: [schedule:write]
      responses:
        "200":
          description: Moved
        "403":
          description: Missing scope or feature disabled