BeeHero
BeeHero API

Bearer-token REST API for BeeHero platform data. Authenticate at /login with email and password to receive an access_token, then read in-hive audio samples by sensor MAC address, read sensor and gateway sample data, rename sensors, and manage gateway configuration (skip-remote, movement interrupt, RSSI configuration). Documented with Swagger UI at docs.beehero.io.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.0
info:
  description: |
    BeeHero API Documentation
    
    READ ME:
    
    To use BeeHero API, it is necessary to first log in and then copy and enter the given `access_token` into Authorize button.
  
  version: 1.0.0
  title: BeeHero API Documentation
  contact:
    email: yuval@beehero.io
tags:
  - name: Auth
    description: Login to BeeHero API
  - name: Audio
    description: Get audio files from sensors
  - name: Sensors
    description: Get sensors sample data
  - name: Gateways
    description: Get gateways sample data
paths:
  /login:
    post:
      tags:
        - Auth
      summary: Login to BeeHero API
      description: >-
        Login to BeeHero API with email and password.

        Please note, once you logged in successfully, the response will include an authorization header -  This access_token header would have to be in the header of each API request below
      operationId: login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: user@mail.com
                  description: User email
                password:
                  type: string
                  example: 1234
                  description: User password
        required: true
      responses:
        "200":
          description: Successful login, a token will be sent in the response body and in
            the set-cookie header
          headers: 
            Set-Cookie:
              schema: 
                type: string
                example: access_token_cookie=abcde12345;
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Login"
        "404":
          description: Login credentials do not match
  /get_audio_samples:
    post:
      tags:
        - Audio
      summary: Get audio samples by mac address
      description: Given a list of mac addresses and begin & end dates, BeeHero will return
        a list of audio samples for sensors with these mac addresses between
        these dates
      operationId: get_audio_sample_by_mac_address
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: array
                  items:
                    type: string
                    description: Mac address list to fetch
                  example:
                    - d0:cf:5e:f7:33:1d
                    - d0:cf:5e:f7:33:1e
                from:
                  type: string
                  example: '2020-10-18'
                  description: "Date to start getting samples from. format: YYYY-MM-DD"
                to:
                  type: string
                  example: '2020-10-18'
                  description: "Last date to get samples from. format: YYYY-MM-DD"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Audio"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
        - bearerAuth: [] 
  /sensors/samples:
    post:
      tags:
        - Sensors
      summary: Get sensors samples by mac address
      description: Given a list of mac addresses and begin & end dates, BeeHero will return
        a list of samples (temperature, humidity, bees' in-count and out-count
        etc) for sensors with these mac addresses between these dates
      operationId: get_sensors_sample_by_mac_address
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: array
                  items:
                    type: string
                    description: mac address to fetch
                  example:
                    - d0:cf:5e:f7:33:1d
                    - d0:cf:5e:f7:33:1e
                from:
                  type: string
                  example: '2020-10-18'
                  description: "Date to start getting samples from. format: YYYY-MM-DD"
                to:
                  type: string
                  example: '2020-10-18'
                  description: "Last date to get samples from. format: YYYY-MM-DD"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sensor"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
        - bearerAuth: [] 
  /sensors/samples_connected:
    post:
      tags:
        - Sensors
      summary: Get sensors connected to a gateway
      description: Given a gateway mac addresses, BeeHero will return
        a list of sensors that are connected to the gateway
      operationId: get_sensors_connected_by_gateway_mac
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    d0:cf:5e:f7:33:1d
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SensorsConnected"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception  
      security:
      - bearerAuth: [] 
  /sensors/update_sensor_name:
    put:
      tags:
        - Sensors
      summary: Update sensor name 
      description: Given a sensor mac address and a name, BeeHero will update
        the sensor's name
      operationId: update_sensor_name
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    d0:cf:5e:f7:33:1d
                name:
                  type: string
                  description: sensor name
                  example:
                    new name
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SensorsUpdateName"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception  
      security:
      - bearerAuth: [] 
  /gateways/samples:
    post:
      tags:
        - Gateways
      summary: Get gateways samples by mac address
      description: Given a list of mac addresses and begin & end dates, BeeHero will return
        a list of samples (temperature, humidity, modem rssi, etc) for gateways with these mac addresses between these dates
      operationId: get_gateways_sample_by_mac_address
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: array
                  items:
                    type: string
                    description: mac address to fetch
                  example:
                    - 00:00:00:00:00:01
                    - 00:0b:57:ce:22:ae
                from:
                  type: string
                  example: '2020-10-18'
                  description: "Date to start getting samples from. format: YYYY-MM-DD"
                to:
                  type: string
                  example: '2020-10-20'
                  description: "Last date to get samples from. format: YYYY-MM-DD"
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Gateway"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
      - bearerAuth: [] 
  /gateways/samples/get_mac_address:
    post:
      tags:
        - Gateways
      summary: Get gateway mac address by external barcode
      description: Given an external barcode BeeHero will return the gateway mac address
      operationId: get_gateway_mac_address
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                external_barcode:
                  type: string
                  description: external barcode to fetch
                  example:
                    12345678
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayGetMac"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
        - bearerAuth: [] 
  /gateways/add_skip_remote:
    put:
      tags:
        - Gateways
      summary: Add SKIP_REMOTE to gateway config by mac address
      description: Given a gateway mac address BeeHero will disable sensor sample
      operationId: add_skip_remote_to_gateway_config
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    00:0b:57:ce:22:ac
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayAddSkipRemote"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
        - bearerAuth: [] 
  /gateways/remove_skip_remote:
    put:
      tags:
        - Gateways
      summary: Remove SKIP_REMOTE from gateway config by mac address
      description: Given a gateway mac address BeeHero will activate gateway config
      operationId: remove_skip_remote_from_gateway_config
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    00:0b:57:ce:22:ac
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayRemoveSkipRemote"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception        
      security:
        - bearerAuth: []
  /gateways/gateway_config_status:
    post:
      tags:
        - Gateways
      summary: Get gateway config status by mac address
      description: Given a mac address, BeeHero will return gateway config status
      operationId: get_gateway_config_status
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    d0:cf:5e:f7:33:1d
        required: true
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayGetSkipRemoteStatus"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
      - bearerAuth: []
  /gateways/movement_interrupt:
    put:
      tags:
        - Gateways
      summary: Configure gateway config movement interrupts by mac address
      description: |
        Given a gateway mac address and movement interrupt field BeeHero will update the gateway config.
        
        - movement_threshold_low - The min threshold of the movement interrupt.
        
        - movement_interrupt_duration - Min duration (seconds) for each movement interrupt.
        
        - movement_interrupt - turn "movement interrupt" on and off (boolean)
      operationId: movement_interrupt_gateway_config
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    00:0b:57:ce:22:ac
                movement_threshold_low:
                  type: integer
                  description: movement threshold low to update
                  example:
                    22
                movement_interrupt_duration:
                  type: integer
                  description: movement threshold duration to update
                  example:
                    2
                movement_interrupt:
                  type: boolean
                  description: movement threshold to update
                  example:
                    true
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayMovementInterrupt"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
        - bearerAuth: [] 
  /gateways/rssi_configuration:
    put:
      tags:
        - Gateways
      summary: Configure gateway configuration by mac address
      description: |
        Given a gateway mac_address, min_rssi and max_remotes, BeeHero will update the gateway config.
        
        - min_rssi - Minimum reception distance.
        
            The recommended range of BeeHero is between -60 to -80. 
        
            The possible range is between -10 to -100.
        
        - max_remotes - The maximum number of remotes connected to the gateway.
        
            The recommended number of BeeHero is 8.
        
            The possible range is between 1 to 12.
        
      operationId: rssi_configuration
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mac:
                  type: string
                  description: mac address to fetch
                  example:
                    00:0b:57:ce:22:ac
                min_rssi:
                  type: integer
                  description: number of min rssi to update
                  example:
                    -60
                max_remotes:
                  type: integer
                  description: number of max remotes to update
                  example:
                    8
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GatewayRssiConfiguration"
        "401":
          description: Login required, user is not logged in
        "403":
          description: Invalid Token
        "404":
          description: Validation exception
      security:
        - bearerAuth: []        
externalDocs:
  description: Find out more about BeeHero
  url: https://www.beehero.io/
servers:
  - url: https://backend.beehero.io/external
components:
  securitySchemes:
    bearerAuth:            
      type: http
      scheme: bearer
      bearerFormat: JWT 
      description: >- 
        Please enter access_token (taken from login response body)
  schemas:
    Audio:
      type: array
      items:
        type: object
        properties:
          mac:
            type: string
            description: Sensor mac address
          audios:
            type: array
            items:
              $ref: "#/components/schemas/AudioObject"
    AudioObject:
      type: object
      properties:
        key:
          type: string
          description: Audio file key
        url:
          type: string
          description: Url to download audio file
    Sensor:
      type: array
      items:
        type: object
        properties:
          gateway_mac_address:
            type: string
            description: Gateway mac address
          sensor_mac_address:
            type: string
            description: Sensor mac address
          temperature:
            type: integer
            description: Temperature from sample
          pcb_temperature_one:
            type: integer
            description: Pcb temperature one from sample
          humidity:
            type: integer
            description: Humidity from sample
          in_count:
            type: integer
            description: Number Of bees entering the hive
          out_count:
            type: integer
            description: Number Of bees exiting the hive
          timestamp:
            type: string
            description: Sample timestamp
          bleRssi:
            type: integer
            description: Signal strength
          external_weight:
            type: integer
            description: Eternal weight
          voltage:
            type: integer
            description: Sensor voltage
          firmware_version:
            type: string
            description: Firmware Version
          message:
            type: string
            description: Message on finding a Mac 
    SensorsConnected:
      type: array
      items:
        type: object
        properties:
          gateway_mac:
            type: string
            description: Gateway mac address
          sensors_conected:
            type: array
            items:
              type: string
              description: Sensors mac addresses connected to the gateway
    SensorsUpdateName:
      type: string
      example:
        Name was successfully changed fron name old to name new name for mac d0:cf:5e:f7:33:1d
    Gateway:
      type: array
      items:
        type: object
        properties:
          gateway_mac_address:
            type: string
            description: Gateway mac address
          humidity:
            type: integer
            description: Humidity from sample
          modem_rssi:
            type: integer
            description: Modem rssi from sample
          latitude:
            type: integer
            description: Latitude from sample
          longitude:
            type: integer
            description: Longitude from sample
          pcb_temperature_two:
            type: integer
            description: Temperature from sample
          timestamp:
            type: string
            description: Sample timestamp
          battery_voltage:
            type: integer
            description: Battery voltage
          firmware_version:
            type: string
            description: Firmware Version
          message:
            type: string
            description: Message on finding a Mac
    GatewayGetMac:
        type: object
        properties:
          gateway_mac_address:
            type: string
            description: Gateway mac address
    GatewayAddSkipRemote:
      type: string
      example:
        SKIP_REMOTE added. Sensor sample disable.
    GatewayRemoveSkipRemote:
      type: string
      example:
        Successful activation.
    Login:
      type: object
      properties:
        access_token:
          type: string
          description: cookie access token
    GatewayGetSkipRemoteStatus:
      type: string
      example:
        Mac d0:cf:5e:f7:33:1d Status Active.
        Movement interrupt On.
        Movement interrupt min threshold 2.
        Min duration (seconds) for each movement interrupt 1.
    GatewayMovementInterrupt:
      type: string
      example:
        Movement interrupt updated successfully.
    GatewayRssiConfiguration:
      type: string
      example: 
        Mac d0:cf:5e:f7:33:1d updated successfully
        Min rssi- -10. 
        Max remotes- 8.
Where this information came from
This is an independent, third-party profile of BeeHero API, published by API Evangelist. We do not operate, host, resell, or support these APIs, and we are not affiliated with or endorsed by the company unless stated above. Everything here is built from publicly available information — the company's own site, developer portal, documentation, public repositories, and the specifications it publishes for public use. Nothing is obtained by breaching a system, defeating an access control, or using credentials.
The Kin Score and Agent Readiness rating are independently calculated assessments of a company's public API artifacts, scored against a published rubric. They are not certifications, endorsements, security assessments, or audits.
Corrections, re-scores, and removal are free — no partnership or purchase required, and you do not need to justify the request. A removed company is recorded as unrated, never scored zero for having asked. Acknowledgement within one business day; removal within two.
info@apievangelist.com · Read the full data-sourcing policy →
On a security or compliance team? Put security in the subject line and you will get a person, not a form — we will tell you exactly which public URLs this profile was built from.
BeeHero API

Documentation

Specifications

Other Resources

OpenAPI Specification
