public-api.yaml

swagger: "2.0"
info:
  title: ForestVPN Public API
  description: |
    ForestVPN defeats content restrictions and censorship to deliver unlimited access to video, music, social media,
    and more, from anywhere in the world.
  termsOfService: https://www.forestvpn.com/terms/
  contact:
    name: Digital Services LLC
    url: https://www.forestvpn.com/
    email: support@forestvpn.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  version: "2.0"

externalDocs:
  description: Find more info here
  url: https://www.forestvpn.com/


host: api.forestvpn.com
basePath: /v2
schemes:
  - https
  - http
consumes:
  - application/json
produces:
  - application/json

securityDefinitions:
  Bearer:
    type: apiKey
    in: header
    name: Authorization

security:
  - Bearer: [ ]

paths:
  /devices/{deviceID}/bindings/:
    get:
      summary: Device bindings
      description: |
        Each device has bindings to specific servers. This method returns hostnames where this device
        bonded at a particular time.
      operationId: BindingList
      tags:
        - device
      parameters:
        - in: path
          name: deviceID
          type: string
          format: uuid
          required: true
          description: |
            Device ID
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/DeviceBindings"
        default:
          description: error
          schema:
            $ref: "#/definitions/Error"
  /devices/{deviceID}/:
    get:
      summary: Device Info
      description: |
        Retrieve device info
      operationId: GetByID
      tags:
        - device
      parameters:
        - in: path
          name: deviceID
          type: string
          format: uuid
          required: true
          description: |
            Device ID
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/DeviceFullDetails"
        default:
          description: error
          schema:
            $ref: "#/definitions/Error"
  /devices/{deviceID}/peers/:
    get:
      summary: Device Peers
      description: |
        Retrieve device peers
      operationId: PeersList
      tags:
        - device
      parameters:
        - in: path
          name: deviceID
          type: string
          format: uuid
          required: true
          description: |
            Device ID
      responses:
        200:
          description: ok
          schema:
            type: array
            items:
              $ref: "#/definitions/DevicePeer"
        default:
          description: error
          schema:
            $ref: "#/definitions/Error"

definitions:
  Error:
    type: object
    properties:
      code:
        type: string
        example: internal_server_error
      message:
        type: string
        example: something went wrong
  Country:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      emoji:
        type: string
  Location:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      latitude:
        type: number
      longitude:
        type: number
      country:
        $ref: "#/definitions/Country"
  IP:
    type: string
  DNS:
    type: string
  Port:
    type: object
    properties:
      src:
        type: integer
      dst:
        type: integer
  WireGuardKey:
    type: string
  WireGuard:
    type: object
    properties:
      priv_key:
        $ref: "#/definitions/WireGuardKey"
      pub_key:
        $ref: "#/definitions/WireGuardKey"
      peers:
        type: array
        items:
          $ref: "#/definitions/WireGuardPeer"
  DeviceStats:
    type: object
    properties:
      connections:
        type: number
      received_bytes:
        type: number
      transmitted_bytes:
        type: number
  DeviceShortDetails:
    type: object
    properties:
      id:
        type: string
        format: uuid
      external_key:
        type: string
      name:
        type: string
      locations:
        type: array
        items:
          $ref: "#/definitions/Location"
      last_active_at:
        type: string
        format: date-time
  DeviceFullDetails:
    type: object
    properties:
      id:
        type: string
        format: uuid
      external_key:
        type: string
      name:
        type: string
      ips:
        type: array
        items:
          $ref: "#/definitions/IP"
        x-go-name: IPs
      dns:
        type: array
        items:
          $ref: "#/definitions/DNS"
      ports:
        type: array
        items:
          $ref: "#/definitions/Port"
      wireguard:
        $ref: "#/definitions/WireGuard"
      locations:
        type: array
        items:
          $ref: "#/definitions/Location"
      last_active_at:
        type: string
        format: date-time
      stats:
        $ref: "#/definitions/DeviceStats"
  DeviceBindings:
    type: array
    items:
      type: string
      example: example.com
  WireGuardPeer:
    type: object
    properties:
      pub_key:
        type: string
      ps_key:
        type: string
      endpoint:
        type: string
      ips:
        type: array
        items:
          $ref: "#/definitions/IP"
        x-go-name: IPs
  DevicePeer:
    type: object
    properties:
      wireguard:
        $ref: "#/definitions/WireGuardPeer"