openapi: 3.1.0
info:
  title: SnapAPI - Screenshot & Web Data Analyze Dashboard API
  version: 2.0.0
  description: 'Professional screenshot, PDF, video, scraping, content extraction, and AI analysis API. Convert any URL into structured data or visual captures with a single API call. Powered by headless Chromium.


    ## Authentication


    All API endpoints (except Auth and Health) require one of:

    - `X-Api-Key: sk_live_xxx` header (recommended for server-side)

    - `Authorization: Bearer sk_live_xxx` header

    - `?access_key=sk_live_xxx` query parameter (for GET endpoints)


    Dashboard endpoints use JWT Bearer tokens obtained from `/auth/login`.


    ## Rate Limits


    | Plan | Requests/month | Rate |

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

    | Free | 100 | 10/min |

    | Starter | 5,000 | 60/min |

    | Pro | 50,000 | 300/min |


    Rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`'
  contact:
    email: support@snapapi.pics
    url: https://snapapi.pics
servers:
- url: https://api.snapapi.pics
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Dashboard
  description: User dashboard — quota overview, API key management, billing, usage history
paths:
  /dashboard/overview:
    get:
      operationId: getDashboardOverview
      summary: Dashboard Overview
      description: Returns user profile, quota usage, monthly stats, daily usage chart data, and active subscription.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Dashboard data
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/UserObject'
                  quota:
                    type: object
                    properties:
                      used:
                        type: integer
                      limit:
                        type: integer
                      remaining:
                        type: integer
                      percentUsed:
                        type: integer
                      resetsAt:
                        type: string
                        format: date-time
                  stats:
                    type: object
                    properties:
                      totalRequests:
                        type: integer
                      successful:
                        type: integer
                      failed:
                        type: integer
                      avgResponseTime:
                        type: integer
                        description: ms
                      totalBytes:
                        type: integer
                      apiKeysCount:
                        type: integer
                  dailyUsage:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: string
                        count:
                          type: integer
                  subscription:
                    type: object
                    nullable: true
        '401':
          description: Unauthorized
        '403':
          description: Email not verified
  /dashboard/api-keys:
    get:
      operationId: listApiKeys
      summary: List API Keys
      description: Returns all API keys for the authenticated user including full key values.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      responses:
        '200':
          description: API keys list
          content:
            application/json:
              schema:
                type: object
                properties:
                  keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKey'
        '401':
          description: Unauthorized
    post:
      operationId: createApiKey
      summary: Create API Key
      description: Create a new API key. Maximum 10 keys per user. Full key value is only returned once on creation.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                  default: New Key
                permissions:
                  type: array
                  items:
                    type: string
                    enum:
                    - screenshot
                    - pdf
                    - metadata
                    - batch
                expiresAt:
                  type: string
                  format: date-time
      responses:
        '200':
          description: API key created — save it now, won't be shown again
        '400':
          description: Maximum 10 keys limit reached
  /dashboard/api-keys/{id}:
    patch:
      operationId: updateApiKey
      summary: Update API Key
      description: Update an API key's name, active status, or permissions.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                isActive:
                  type: boolean
                permissions:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Updated
        '404':
          description: Key not found
    delete:
      operationId: deleteApiKey
      summary: Delete API Key
      description: Delete an API key. Cannot delete the last remaining key.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
        '400':
          description: Cannot delete last API key
        '404':
          description: Key not found
  /dashboard/api-keys/{id}/regenerate:
    post:
      operationId: regenerateApiKey
      summary: Regenerate API Key
      description: Generate a new key value for an existing key entry. Old key is immediately invalidated.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: New key value returned — save it now
        '404':
          description: Key not found
  /dashboard/usage:
    get:
      operationId: getUsageHistory
      summary: Usage History
      description: Paginated list of API calls with endpoint, options, response time, status code, and error details.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      - name: apiKeyId
        in: query
        schema:
          type: string
        description: Filter by specific API key
      responses:
        '200':
          description: Usage records
          content:
            application/json:
              schema:
                type: object
                properties:
                  records:
                    type: array
                    items:
                      type: object
                  pagination:
                    type: object
                    properties:
                      limit:
                        type: integer
                      offset:
                        type: integer
                      hasMore:
                        type: boolean
  /dashboard/billing:
    get:
      operationId: getBilling
      summary: Billing Info
      description: Returns the current subscription and payment history.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Billing info
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscription:
                    type: object
                    nullable: true
                  payments:
                    type: array
                    items:
                      type: object
  /dashboard/plans:
    get:
      operationId: getPlans
      summary: Available Plans
      description: Returns all available subscription plans with pricing, quotas, and features.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Plan list
          content:
            application/json:
              schema:
                type: object
                properties:
                  plans:
                    type: array
                    items:
                      type: object
  /dashboard/create-checkout:
    post:
      operationId: createCheckout
      summary: Create Checkout
      description: Returns a Paddle price ID and customer email for the frontend to open a Paddle.js checkout overlay.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - planId
              - interval
              properties:
                planId:
                  type: string
                interval:
                  type: string
                  enum:
                  - monthly
                  - yearly
      responses:
        '200':
          description: Paddle checkout params
        '404':
          description: Plan not found
  /dashboard/cancel-subscription:
    post:
      operationId: cancelSubscription
      summary: Cancel Subscription
      description: Cancel the active subscription at period end. Access remains until current billing period expires.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Cancellation scheduled
        '400':
          description: No active subscription
        '502':
          description: Paddle API error
  /dashboard/profile:
    patch:
      operationId: updateProfile
      summary: Update Profile
      description: Update the authenticated user's display name.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
      responses:
        '200':
          description: Profile updated
        '400':
          description: No fields to update
  /dashboard/change-password:
    post:
      operationId: changePassword
      summary: Change Password
      description: Change password for email/password accounts. Not available for OAuth-only accounts.
      tags:
      - Dashboard
      security:
      - BearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - currentPassword
              - newPassword
              properties:
                currentPassword:
                  type: string
                newPassword:
                  type: string
                  minLength: 8
      responses:
        '200':
          description: Password updated
        '400':
          description: Current password incorrect or OAuth account
components:
  schemas:
    ApiKey:
      type: object
      properties:
        id:
          type: string
        key:
          type: string
          description: Full key value (only returned on create/regenerate)
          example: sk_live_abc123...
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
        expiresAt:
          type: string
          format: date-time
          nullable: true
        isActive:
          type: boolean
        permissions:
          type: array
          items:
            type: string
            enum:
            - screenshot
            - pdf
            - metadata
            - batch
    UserObject:
      type: object
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        name:
          type: string
        plan:
          type: string
          enum:
          - free
          - starter
          - pro
        avatarUrl:
          type: string
          nullable: true
        emailVerified:
          type: boolean
        isAdmin:
          type: boolean
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your SnapAPI API key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/login or /auth/refresh