Autoposting.ai Usage API

openapi: 3.2.0
info:
  title: Autoposting Usage API
  description: 'Schedule, publish, and AI-enhance social content across X, LinkedIn, Instagram, Threads, and YouTube. All responses use the `{ "success": boolean, "data": ... }` envelope. Authenticate with an API key (`Authorization: Bearer sk-social-...` or `x-api-key: sk-social-...`).'
  version: 1.0.0
servers:
- url: https://app.autoposting.ai/api-proxy
  description: Production
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Usage
  description: Usage summaries, token breakdowns, feature access, onboarding progress, and account management endpoints.
paths:
  /usage/summary:
    get:
      tags:
      - Usage
      summary: Get usage summary for the org
      description: Returns an aggregate view of the organization's resource usage for the current billing period.
      operationId: getUsageSummary
      responses:
        '200':
          description: Aggregate usage summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/UsageSummary'
                required:
                - success
                - data
              example:
                success: true
                data:
                  period:
                    start: '2024-01-01T00:00:00Z'
                    end: '2024-02-01T00:00:00Z'
                  posts:
                    published: 42
                    scheduled: 8
                    failed: 2
                  clips:
                    uploaded: 5
                    rendered: 12
                  agents:
                    runs: 30
                    postsGenerated: 28
                  credits:
                    allocated: 500
                    used: 187
                    remaining: 313
                  aiTokens:
                    total: 1250000
                    used: 482000
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /usage/tokens:
    get:
      tags:
      - Usage
      summary: Get token-level usage breakdown
      description: Detailed breakdown of AI token consumption by feature and time period.
      operationId: getTokenUsage
      parameters:
      - name: period
        in: query
        required: false
        description: 'Time period: 7d, 30d, 90d. Default: 30d.'
        schema:
          type: string
          enum:
          - 7d
          - 30d
          - 90d
          default: 30d
      responses:
        '200':
          description: Token usage breakdown.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/TokenUsage'
                required:
                - success
                - data
              example:
                success: true
                data:
                  period: 30d
                  total: 482000
                  breakdown:
                    agents: 210000
                    ideaGeneration: 95000
                    carouselGeneration: 80000
                    postRewrite: 52000
                    captionGeneration: 30000
                    other: 15000
                  dailyUsage:
                  - date: '2024-01-10'
                    tokens: 18000
                  - date: '2024-01-09'
                    tokens: 14000
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /features/access:
    get:
      tags:
      - Usage
      summary: Check feature access for current org
      description: Returns which features the current organization has access to, based on plan and grants.
      operationId: getFeatureAccess
      responses:
        '200':
          description: Feature access map.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/FeatureAccess'
                required:
                - success
                - data
              example:
                success: true
                data:
                  clips: true
                  agents: true
                  carousels: true
                  knowledgeBase: true
                  teamManagement: true
                  apiKeys: true
                  webhooks: false
                  customDomains: false
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /features/interest:
    post:
      tags:
      - Usage
      summary: Register interest in a feature
      description: Signal interest in a feature that is not yet available on your plan. Used internally for roadmap prioritization.
      operationId: registerFeatureInterest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                feature:
                  type: string
                  description: Feature identifier (e.g., "webhooks", "custom_domains").
                comment:
                  type: string
                  description: Optional note about your use case.
              required:
              - feature
            example:
              feature: webhooks
              comment: Need real-time delivery events.
      responses:
        '200':
          description: Interest registered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      registered:
                        type: boolean
                    required:
                    - registered
                required:
                - success
                - data
              example:
                success: true
                data:
                  registered: true
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /onboarding/status:
    get:
      tags:
      - Usage
      summary: Get onboarding progress
      operationId: getOnboardingStatus
      responses:
        '200':
          description: Onboarding progress.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/OnboardingStatus'
                required:
                - success
                - data
              example:
                success: true
                data:
                  completed: false
                  steps:
                    createBrand: true
                    connectPlatform: true
                    createFirstPost: false
                    inviteTeamMember: false
                  completedAt: null
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /onboarding/progress:
    post:
      tags:
      - Usage
      summary: Save onboarding step progress
      operationId: saveOnboardingProgress
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                step:
                  type: string
                  description: Step identifier to mark as completed (e.g., "createFirstPost").
              required:
              - step
            example:
              step: createFirstPost
      responses:
        '200':
          description: Step progress saved.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      step:
                        type: string
                      completed:
                        type: boolean
                    required:
                    - step
                    - completed
                required:
                - success
                - data
              example:
                success: true
                data:
                  step: createFirstPost
                  completed: true
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /onboarding/complete:
    post:
      tags:
      - Usage
      summary: Mark onboarding as complete
      description: Marks the entire onboarding flow as finished, regardless of step completion state.
      operationId: completeOnboarding
      responses:
        '200':
          description: Onboarding marked complete.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      completed:
                        type: boolean
                    required:
                    - completed
                required:
                - success
                - data
              example:
                success: true
                data:
                  completed: true
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /account:
    delete:
      tags:
      - Usage
      summary: Delete user account
      description: Permanently deletes the authenticated user's account and all personal data. This action is irreversible. All organizations where the user is the sole owner must be deleted or transferred first. If the user belongs to organizations with other members, their membership is removed but the organizations persist.
      operationId: deleteAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                confirm:
                  type: boolean
                  description: Must be true to confirm deletion.
              required:
              - confirm
            example:
              confirm: true
      responses:
        '200':
          description: Account deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: object
                    properties:
                      deleted:
                        type: boolean
                    required:
                    - deleted
                required:
                - success
                - data
              example:
                success: true
                data:
                  deleted: true
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
  /account/export:
    get:
      tags:
      - Usage
      summary: Export account data
      description: Generates and returns a downloadable export of all data associated with the account (GDPR-compliant data portability). Export generation may take a few seconds for accounts with large amounts of data. The download URL is time-limited and expires after 24 hours.
      operationId: exportAccountData
      responses:
        '200':
          description: Account data export.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    $ref: '#/components/schemas/AccountExport'
                required:
                - success
                - data
              example:
                success: true
                data:
                  downloadUrl: https://exports.autoposting.ai/usr_01HXYZ/export-20240110.zip?signature=...
                  expiresAt: '2024-01-11T00:00:00Z'
                  sizeBytes: 2048000
        '401':
          description: Authentication required or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: unauthorized
                message: Missing or invalid API key.
components:
  schemas:
    TokenUsage:
      type: object
      properties:
        period:
          type: string
          example: 30d
        total:
          type: integer
        breakdown:
          type: object
          properties:
            agents:
              type: integer
            ideaGeneration:
              type: integer
            carouselGeneration:
              type: integer
            postRewrite:
              type: integer
            captionGeneration:
              type: integer
            other:
              type: integer
        dailyUsage:
          type: array
          items:
            $ref: '#/components/schemas/DailyTokenUsage'
      required:
      - period
      - total
      - breakdown
      - dailyUsage
    OnboardingStatus:
      type: object
      properties:
        completed:
          type: boolean
        steps:
          type: object
          properties:
            createBrand:
              type: boolean
            connectPlatform:
              type: boolean
            createFirstPost:
              type: boolean
            inviteTeamMember:
              type: boolean
        completedAt:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - completed
      - steps
      - completedAt
    AccountExport:
      type: object
      properties:
        downloadUrl:
          type: string
          format: uri
        expiresAt:
          type: string
          format: date-time
        sizeBytes:
          type: integer
      required:
      - downloadUrl
      - expiresAt
      - sizeBytes
    FeatureAccess:
      type: object
      properties:
        clips:
          type: boolean
        agents:
          type: boolean
        carousels:
          type: boolean
        knowledgeBase:
          type: boolean
        teamManagement:
          type: boolean
        apiKeys:
          type: boolean
        webhooks:
          type: boolean
        customDomains:
          type: boolean
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          const: false
        error:
          type: string
        message:
          type: string
      required:
      - success
      - error
      - message
    UsageSummary:
      type: object
      properties:
        period:
          type: object
          properties:
            start:
              type: string
              format: date-time
            end:
              type: string
              format: date-time
          required:
          - start
          - end
        posts:
          type: object
          properties:
            published:
              type: integer
            scheduled:
              type: integer
            failed:
              type: integer
        clips:
          type: object
          properties:
            uploaded:
              type: integer
            rendered:
              type: integer
        agents:
          type: object
          properties:
            runs:
              type: integer
            postsGenerated:
              type: integer
        credits:
          type: object
          properties:
            allocated:
              type: integer
            used:
              type: integer
            remaining:
              type: integer
        aiTokens:
          type: object
          properties:
            total:
              type: integer
            used:
              type: integer
      required:
      - period
      - posts
      - clips
      - agents
      - credits
      - aiTokens
    DailyTokenUsage:
      type: object
      properties:
        date:
          type: string
          format: date
        tokens:
          type: integer
      required:
      - date
      - tokens
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key as `Authorization: Bearer sk-social-...`'
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key as `x-api-key: sk-social-...`'