xpoz-ai Account API

openapi: 3.2.0
info:
  title: XPOZ Account API
  version: 1.0.0
  description: 'Social media data API for Twitter/X, Instagram, Reddit, and TikTok.


    **Data endpoints** (`/api/data/*`) are authenticated with an API access key and are metered against the account''s credits. Most stored-data endpoints share the same query options: `fields` selects which attributes to return, `since`/`until` bound the date range, and `responseType` picks between a synchronous first page (`fast`), a full paged query run as a background operation (`paging`), and a CSV export (`csv`). `/live` endpoints fetch from the platform on demand and page with a cursor instead.


    **Account, billing, and crawl-settings endpoints** are used by the XPOZ dashboard and authenticate with the user''s session.'
servers:
- url: /
  description: This server
tags:
- name: Account
  description: Access keys, plan, and usage of the signed-in user.
paths:
  /api/tokens:
    get:
      tags:
      - Account
      summary: List access keys
      description: List the caller's active API access keys.
      security:
      - UserSession: []
      responses:
        '200':
          description: Access keys.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AccessKeyRecord'
                  count:
                    type: integer
                required:
                - success
                - data
                - count
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getTokens
    post:
      tags:
      - Account
      summary: Create an access key
      description: 'Create an API access key for the caller, or return the existing one (`isExisting: true`).'
      security:
      - UserSession: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
      responses:
        '200':
          description: Access key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessKeyCreated'
        '400':
          description: Missing user data on the session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: postTokens
  /api/tokens/rotate:
    post:
      tags:
      - Account
      summary: Rotate access key
      description: Revoke the caller's current access key and issue a new one.
      security:
      - UserSession: []
      responses:
        '200':
          description: New access key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessKeyCreated'
        '400':
          description: Missing user data on the session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimpleError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: postTokensRotate
  /api/plan:
    get:
      tags:
      - Account
      summary: Get current plan
      description: The caller's subscription plan and its features.
      security:
      - UserSession: []
      responses:
        '200':
          description: Plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plan'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getPlan
  /api/usage:
    get:
      tags:
      - Account
      summary: Get usage
      description: Credits and CSV rows used this period, plus purchased extras.
      security:
      - UserSession: []
      responses:
        '200':
          description: Usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getUsage
  /api/usage-history:
    get:
      tags:
      - Account
      summary: Get usage history
      description: Credits and export rows used per time bucket.
      security:
      - UserSession: []
      parameters:
      - name: range
        in: query
        required: false
        description: Time range.
        schema:
          type: string
          enum:
          - today
          - 7d
          - current_month
          - lifetime
          default: current_month
      - name: granularity
        in: query
        required: false
        description: Bucket size.
        schema:
          type: string
          enum:
          - hour
          - day
          default: day
      responses:
        '200':
          description: Usage history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageHistory'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedMessage'
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyFailure'
      operationId: getUsageHistory
components:
  responses:
    ValidationError:
      description: Query or body validation failed. `message` joins all validation issues with `, `.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SimpleError'
    UnauthorizedMessage:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MessageError'
  schemas:
    SimpleError:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
      required:
      - success
      - message
    LegacyFailure:
      type: object
      properties:
        success:
          type: boolean
          const: false
        message:
          type: string
        error:
          type: string
      required:
      - success
      - message
    AccessKeyCreated:
      type: object
      properties:
        success:
          type: boolean
          const: true
        data:
          type: object
          properties:
            id:
              type: string
            accessKey:
              type: string
            accessKeyPrefix:
              type: string
            keyName:
              type: string
            expiresAt:
              anyOf:
              - type: string
                format: date-time
              - type: 'null'
            createdAt:
              type: string
              format: date-time
          required:
          - id
          - accessKey
          - accessKeyPrefix
          - keyName
          - createdAt
        message:
          type: string
        isExisting:
          type: boolean
      required:
      - success
      - data
      - message
      - isExisting
    UsageHistory:
      type: object
      properties:
        range:
          type: string
          enum:
          - today
          - 7d
          - current_month
          - lifetime
        granularity:
          type: string
          enum:
          - hour
          - day
        generatedAt:
          type: string
          format: date-time
        credits:
          type: array
          items:
            $ref: '#/components/schemas/UsageBucket'
        exportRows:
          type: array
          items:
            $ref: '#/components/schemas/UsageBucket'
      required:
      - range
      - granularity
      - generatedAt
      - credits
      - exportRows
    Usage:
      type: object
      properties:
        creditsUsed:
          type: number
        extraCreditsBalance:
          type: number
        csvRowsUsed:
          type: number
        extraCsvRowsBalance:
          type: number
      required:
      - creditsUsed
      - extraCreditsBalance
      - csvRowsUsed
      - extraCsvRowsBalance
    Plan:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        features:
          $ref: '#/components/schemas/PlanFeatures'
        stripeProductId:
          type: string
        extraTrackedItemPriceId:
          anyOf:
          - type: string
          - type: 'null'
        description:
          type: string
        price:
          type: number
        currency:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
      required:
      - id
      - name
      - features
      - price
      - currency
    AccessKeyRecord:
      type: object
      properties:
        id:
          type: string
        descopeUserId:
          type: string
        userEmail:
          type: string
        userName:
          type: string
        authProvider:
          type: string
        authProviderId:
          type: string
        accessKeyId:
          type: string
        accessKey:
          type: string
        accessKeyPrefix:
          type: string
        keyName:
          type: string
        tenantId:
          type: string
        createdAt:
          type: string
          format: date-time
        expiresAt:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
        isActive:
          type: boolean
        metadata:
          type: object
    UsageBucket:
      type: object
      properties:
        bucket:
          type: string
        subscriptionUsed:
          type: number
        extraUsed:
          type: number
        totalUsed:
          type: number
        extraPurchased:
          type: number
      required:
      - bucket
      - subscriptionUsed
      - extraUsed
      - totalUsed
      - extraPurchased
    MessageError:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    PlanFeatures:
      type: object
      properties:
        credits:
          type: number
        creditResetFrequency:
          type: string
          enum:
          - monthly
          - never
        extraCreditPrice:
          type: number
        trackedItems:
          type: number
        csvRowExportLimit:
          type: number
        extraCsvRowPrice:
          type: number
        extraTrackedItemPrice:
          type: number
        maxRowsPerExport:
          type: number
      required:
      - credits
      - creditResetFrequency
      - extraCreditPrice
      - trackedItems
      - csvRowExportLimit
      - extraCsvRowPrice
      - extraTrackedItemPrice
  securitySchemes:
    AccessKey:
      type: http
      scheme: bearer
      description: 'XPOZ API access key, created from the dashboard or `POST /api/tokens`. Send as `Authorization: Bearer <access key>`.'
    UserSession:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Descope session JWT of a logged-in dashboard user. Send as `Authorization: Bearer <session JWT>`.'