xpoz-ai Platform API

openapi: 3.2.0
info:
  title: XPOZ Platform 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: Platform
  description: Health, metrics, and this spec.
paths:
  /health:
    get:
      tags:
      - Platform
      summary: Health check
      description: Liveness and dependency health. Returns 503 when SingleStore is unhealthy.
      security: []
      responses:
        '200':
          description: Healthy or degraded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
        '503':
          description: Unhealthy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthStatus'
      operationId: getHealth
  /metrics:
    get:
      tags:
      - Platform
      summary: Prometheus metrics
      description: Prometheus exposition format.
      security: []
      responses:
        '200':
          description: Metrics.
          content:
            text/plain:
              schema:
                type: string
      operationId: getMetrics
  /openapi.yaml:
    get:
      tags:
      - Platform
      summary: OpenAPI spec (YAML)
      description: This document.
      security: []
      responses:
        '200':
          description: Spec.
          content:
            application/yaml:
              schema:
                type: string
      operationId: getOpenapi.yaml
  /openapi.json:
    get:
      tags:
      - Platform
      summary: OpenAPI spec (JSON)
      description: This document.
      security: []
      responses:
        '200':
          description: Spec.
          content:
            application/json:
              schema:
                type: object
      operationId: getOpenapi.json
components:
  schemas:
    HealthStatus:
      type: object
      properties:
        status:
          type: string
          enum:
          - healthy
          - degraded
          - unhealthy
        version:
          type: string
        uptime:
          type: number
          description: Seconds.
        timestamp:
          type: string
          format: date-time
        dependencies:
          type: object
          properties:
            singlestore:
              $ref: '#/components/schemas/ServiceHealth'
          required:
          - singlestore
      required:
      - status
      - version
      - uptime
      - timestamp
      - dependencies
    ServiceHealth:
      type: object
      properties:
        status:
          type: string
          enum:
          - healthy
          - degraded
          - unhealthy
        responseTime:
          type: number
        error:
          type: string
      required:
      - status
  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>`.'