openapi: 3.0.0

info:
  title: LabVPN Reseller API
  version: 2.0.0
  description: |
    ## Overview

    Welcome to the **LabVPN Reseller API**.

    This API allows **LabVPN resellers** to programmatically manage, control, and automate VPN services provided through the LabVPN platform.
    It is intended for integration with custom dashboards, automation scripts, billing systems, and internal reseller tools.

    If you do not yet have reseller access or an API token, please contact **[LabVPN Support via Telegram](https://t.me/LabVPNSup)**.

    ---

    ## Authentication

    All API requests **must include a valid API token**.

    - Each reseller is issued a unique API token
    - The token must be sent in the request headers
    - Requests without a valid token will be rejected

    To obtain an API token, contact **[LabVPN Support on Telegram](https://t.me/LabVPNSup)**.

    ---

    ## Request Format

    - All endpoints use **HTTPS POST** requests
    - Request parameters must be sent as **JSON in the request body**
    - Query parameters are not supported

    ---

    ## Response Format

    All API responses share a common structure and are returned as JSON objects containing:

    - **ok** *(boolean)* — Indicates whether the request was successful
    - **runtime** *(integer)* — Time taken to process the request (milliseconds)
    - **code** *(integer)* — Numeric status or error code
    - **label** *(string)* — Short UPPER_SNAKE_CASE identifier describing the result
    - **result** *(object)* — Endpoint-specific response payload, **Only when ok = true**
    - **description** *(string)* - Description related to label, **Only when ok = false**

    ---

    ## Response Code Ranges

    - **200–299** → Successful requests  
    - **400–499** → Invalid requests, missing parameters, or permission errors  
    - **500–599** → Internal server errors  

servers:
  - url: https://api.labex.pro

paths:

  /getServices:
    post:
      summary: Retrieve services
      tags:
        - Services
      description: |
        Returns services available under the reseller control.

        By default, all service types are returned with a maximum of 100 results.
        Optional filters may be applied to limit the response.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                offset:
                  type: integer
                  minimum: 0
                  description: |
                    Pagination offset.

                    The API returns a maximum of 100 services per request.
                    This value specifies the starting offset.
                  example: 0
                client:
                  type: string
                  description: |
                    Client identifier.

                    When provided, only the service associated with this client-ID
                    will be returned.
                  example: "1:1"
                type:
                  type: array
                  description: |
                    Optional service status filter.

                    If omitted or empty, services of all types are returned.
                    Multiple values may be provided.
                  items:
                    type: string
                    enum:
                      - active
                      - expired
                      - conn_limited
                  example:
                    - active
                    - expired
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object

  /create:
    post:
      summary: Create new service
      tags:
        - Services
      description: Creates a new VPN service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [time, name, conn_limit]
              properties:
                time:
                  type: integer
                  description: Service duration in seconds
                  example: 1000
                name:
                  type: string
                  description: Custom service name
                  example: "Test"
                conn_limit:
                  type: integer
                  description: Maximum parallel connections
                  example: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                type: object

  /renew:
    post:
      summary: Extend service expiration
      tags:
        - Services
      description: Extends the expiration time of an active service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client, time]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
                time:
                  type: integer
                  description: Extension duration in seconds
                  example: 1000
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                type: object

  /relive:
    post:
      summary: Reactivate expired service
      tags:
        - Services
      description: Restores a service that has expired.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                type: object

  /return:
    post:
      summary: Refund service
      tags:
        - Services
      description: Refunds the remaining balance of a service and closes it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                type: object

  /rename:
    post:
      summary: Update service name
      tags:
        - Services
      description: Changes the display name of a service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client, name]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
                name:
                  type: string
                  description: New service name
                  example: "Test"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object

  /renote:
    post:
      summary: Update service note
      tags:
        - Services
      description: Updates or clears the note associated with a service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client, note]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
                note:
                  type: string
                  description: New note text
                  example: "Note"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object

  /changeConnLimit:
    post:
      summary: Change connection limit
      tags:
        - Services
      description: Updates the maximum number of parallel connections.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client, limit]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
                limit:
                  type: integer
                  description: New connection limit
                  example: 3
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                type: object

  /resetConnect:
    post:
      summary: Revoke connection links
      tags:
        - Services
      description: Revokes all direct and subscription connection links.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Something went wrong
          content:
            application/json:
              schema:
                type: object

  /resetTraffic:
    post:
      summary: Reset traffic usage
      tags:
        - Services
      description: Resets upload and download traffic counters to zero.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [client]
              properties:
                client:
                  type: string
                  description: Client identifier
                  example: "1:1"
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Missing something
          content:
            application/json:
              schema:
                type: object

  /getMe:
    post:
      summary: Get my info
      tags:
        - Account
      description: Gathers information about the reseller.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object

  /getRate:
    post:
      summary: Get plans info
      tags:
        - Account
      description: Get available plans and pricing information.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object

components:

  securitySchemes:
    LabVPN-API-Token:
      type: apiKey
      in: header
      name: LabVPN-API-Token

  schemas:

    BaseResponse:
      type: object
      description: Common response envelope used by all API endpoints
      required: [ok, runtime, code, label, result]
      properties:
        ok:
          type: boolean
          description: Indicates whether the request was successful
          example: true
        runtime:
          type: integer
          description: Request processing time in milliseconds
          example: 21
        code:
          type: integer
          description: Numeric status or error code
          example: 200
        label:
          type: string
          description: Short UPPER_SNAKE_CASE identifier describing the result
          example: SUCCESSFUL
        result:
          type: object
          description: Endpoint-specific response payload
          oneOf:
            - $ref: "#/components/schemas/List"

    List:
      type: object
      description: Paginated list of client services
      required: [count, offset, list]
      properties:
        count:
          type: integer
          description: Number of items returned
          example: 1
        offset:
          type: integer
          description: Pagination offset
          example: 0
        list:
          type: array
          description: List of services (maximum 100 per request)
          items:
            $ref: "#/components/schemas/Client"

    Client:
      type: object
      description: VPN service information
      required:
        - client
        - number
        - created
        - expires
        - name
        - note
        - conn_limit
        - location
        - switch
        - traffic
      properties:
        client:
          type: string
          example: "1:1"
          description: Unique client identifier (`number:number`)
        number:
          type: integer
          example: 1
          description: Sequential client number
        created:
          type: integer
          example: 1700000000
          description: Service creation time (Unix timestamp)
        expires:
          type: integer
          example: 1705000000
          description: Service expiration time (Unix timestamp, 0 = never)
        name:
          type: string
          example: "Test"
          description: Service display name
        note:
          type: string
          example: "Note"
          description: Optional service note
        conn_limit:
          type: integer
          example: 1
          description: Maximum parallel connections (0 = unlimited)
        location:
          type: string
          example: "DE-01"
          description: Assigned server location
        switch:
          type: array
          description: Feature switches applied to the service
          items:
            $ref: "#/components/schemas/Switch"
        traffic:
          type: array
          description: Traffic usage statistics
          items:
            $ref: "#/components/schemas/Traffic"
        connect:
          type: array
          description: Connection information
          items:
            $ref: "#/components/schemas/Connect"

    Switch:
      type: object
      description: Service feature switches
      required: [porn, ads]
      properties:
        porn:
          type: boolean
          example: true
          description: Allows or blocks adult content
        ads:
          type: boolean
          example: false
          description: Allows or blocks advertisements

    Traffic:
      type: object
      description: Traffic usage information
      required: [upload, download]
      properties:
        upload:
          type: integer
          example: 1048576
          description: Uploaded data in bytes
        download:
          type: integer
          example: 2097152
          description: Downloaded data in bytes

    Connect:
      type: object
      description: Service connection details
      required: [direct, subscription, qrcode]
      properties:
        direct:
          type: string
          example: "vmess://example"
          description: Direct connection link
        subscription:
          type: string
          example: "https://sub.labex.pro/client"
          description: Subscription link containing all configurations
        qrcode:
          type: string
          example: "https://api.realix.pro/QRCode/client"
          description: QRcode for the direct connection link

    Me:
      type: object
      description: Account information
      required: [balance, label, webhook_url]
      properties:
        balance:
          type: integer
          example: 0
          description: The amount of money on users panel
        label:
          type: string
          example: "CustomVPN"
          description: Custom branding name on services
        webhook_url:
          type: string
          example: "https://api.labex.pro/webhook"
          description: The webhook-url to receive updates

    Rate:
      type: array
      description: Plans and price information
      items:
        type: object
        required: [conn_limit, monthly_price]
        properties:
          conn_limit:
            type: integer
            example: 1
            description: Maximum parallel connections (0 = unlimited)
          monthly_price:
            type: integer
            example: 0
            description: Needed price to buy 1-month of this service

security:
  - LabVPN-API-Token: []
