KISI Readers API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Readers API
  description: "## Introduction\n\nWelcome to the Kisi API documentation. Before you read further, please read\nthe general [Kisi Docs portal](https://docs.kisi.io/).\n\n<!-- theme: info -->\n> If you want to be notified by email about updates to our API, please subscribe to our\n> [newsletter](https://2e2bc.share.hsforms.com/2OsdqtC8xRHGQ2yaS16AF7w).\n\n### Format\n\nThe Kisi API supports JSON only, so please set `Accept` and `Content-Type`\nto `application/json`. All requests and responses will use JSON as the\nformat for any data encompassed in the body of requests and responses.\n\n```http\n<METHOD> <URL> HTTP/1.1\nAccept: application/json\nContent-Type: application/json\n```\n\n### Authentication\n\nMost calls to the API will require an authenticated user. If such a user\nis not present, you will receive a 401 response.\nFor more information about authentication, see the [Kisi Docs portal](https://docs.kisi.io/api/get_started/add_necessary_headers).\n\nAPI calls must be made using HTTPS. Any calls made over plain HTTP will fail.\n\n### Rate limits\n\nFor authenticated API requests, you can make up to 5 requests per second,\nper user. Note that the limit applies per user, so requests made using\ndifferent logins for the same user share the same quota.\n\nFor unauthenticated requests, you can make up to 5 requests per second, per\nIP address.\n\nThe following endpoints have custom rate limits:\n\n| Endpoint                   | Limit            |\n|----------------------------|------------------|\n| `POST /event_sets`         | 1 per second     |\n| `POST /signed_upload_urls` | 1 per 10 seconds |\n\nIf you exceed the rate limit, a 429 response will be returned.\n\nSome best practices:\n- If you're making requests for a single user, do so serially, *not* concurrently.\n- If you're making a large number of requests for a single user, wait at least one second between each request.\n\nWe reserve the right to change these limits as needed to ensure availability.\n\n### Deprecations\n\nIn the event that some part of the API has to be deprecated, we do the following:\n\n  1. Return the `Deprecation` header with the date of when the endpoint is deprecated.\n  2. Return the `Sunset` header with the date of when the endpoint can be expected to not function anymore.\n  3. When the `Sunset` date is reached, the endpoint may go away at any time.\n\nWe recommend listening to these headers to avoid disruptions.\n\n### Error codes\n\nSome endpoints return an error code and a message. In the table below all error codes are listed.\n\n| Error code | Message                                                                                         |\n|------------|-------------------------------------------------------------------------------------------------|\n| `afc507`   | The authentication link is not valid.                                                           |\n| `afc546`   | Invalid Two Factor backup code.                                                                 |\n| `faa9ff`   | The card is not activated.                                                                      |\n| `faa9ef`   | The card was not found.                                                                         |\n| `afc496`   | Access denied.                                                                                  |\n| `f29aef`   | Your link is invalid.                                                                           |\n| `afc516`   | Wrong email address or password.                                                                |\n| `afc536`   | Invalid Two Factor verification code.                                                           |\n| `afc526`   | Please provide a Two Factor verification code.                                                  |\n| `afc516`   | The two factor pin is invalid                                                                   |\n| `ffffff`   | An unexpected issue occured.                                                                    |\n| `fcd8ef`   | Access denied.                                                                                  |\n| `fcd8ff`   | Access disabled.                                                                                |\n| `cabbeb`   | A card with the same identifiers was already enrolled.                                          |\n| `bb4fff`   | Please authorize Kisi for Bluetooth.                                                            |\n| `bb5bff`   | No nearby Kisi reader found. Try enabling Bluetooth on your device.                             |\n| `bb4bff`   | Please enable Bluetooth.                                                                        |\n| `a7793f`   | Please authorize Kisi for location services.                                                    |\n| `a3799f`   | Please enable your location services.                                                           |\n| `a3793f`   | Please enable your location services.                                                           |\n| `f298cf`   | The place has disabled all links for you.                                                       |\n| `f298df`   | Your access rights for this place do not include links.                                         |\n| `f298bf`   | Your access right is invalid.                                                                   |\n| `f01337`   | Your group's access rights for this place do not include apps.                                  |\n| `34bd8f`   | Your device is not the primary one.                                                             |\n| `facced`   | Unable to decode the certificate.                                                               |\n| `bbb99f`   | Your location is not valid.                                                                     |\n| `bbb93f`   | The location of the lock is invalid.                                                            |\n| `a3995f`   | You are too far away.                                                                           |\n| `bb4faa`   | You're not close enough to the door.                                                            |\n| `bbc93f`   | In-app access is disabled by the organization. Please tap your phone against the reader.        |\n| `34ffaa`   | Your access is not allowed at this moment, please try again later.                              |\n| `f35ade`   | Your access is no longer valid.                                                                 |\n| `f398de`   | Your access is invalid.,                                                                        |\n| `f358de`   | Your access is not yet valid, please try again later.                                           |\n| `fad334`   | An error occurred permitting the the elevator stop.                                             |\n| `fad121`   | The elevator stop was not found.                                                                |\n| `fad122`   | The elevator stop was not configured.                                                           |\n| `fad123`   | The elevator stops are locked down.                                                             |\n| `fad124`   | The elevator stop was on schedule.                                                              |\n| `fad002`   | The place is currently locked down.                                                             |\n| `ff420a`   | The door has no assigned Kisi controller.                                                       |\n| `fad001`   | The door is currently locked down.                                                              |\n| `fad105`   | The door is improperly configured.                                                              |\n| `fad10e`   | The door could not be found.                                                                    |\n| `fad110`   | The door is already scheduled to be unlocked.                                                   |\n| `fad137`   | The access was denied by the zone.                                                              |\n| `fad146`   | The third party zone was overriden but it is still armed.                                       |\n| `fad10f`   | An error occurred connecting to the wireless lock.                                              |\n| `fad106`   | An error occurred finding the wireless lock.                                                    |\n| `fad107`   | The wireless lock is offline.                                                                   |\n| `fad112`   | An unlock is already in progress for the wireless lock.                                         |\n| `fac001`   | The Kisi controller is currently unavailable.                                                   |\n| `fac002`   | The Kisi controller is currently unavailable.                                                   |\n| `fac003`   | The Kisi device is currently unavailable.                                                       |\n| `fac004`   | The Kisi device is currently unavailable.                                                       |\n| `fad108`   | The Kisi controller is not yet configured.                                                      |\n| `ecc123`   | The Kisi controller encountered an unhandled error.                                             |\n| `fbc000`   | The Kisi controller firmware is being updated. This will take a few seconds. Please retry then. |\n| `aaa345`   | The zone has no assigned zone controller.                                                       |\n| `fad126`   | The zone could not be found.                                                                    |\n| `fad129`   | The alarm controller is currently unavailable.                                                  |\n| `adf234`   | An error occurred resetting the zone.                                                           |\n| `fad144`   | The third party alarm is still in violation.                                                    |\n| `abbb11`   | The integration partner experienced an error.                                                   |\n| `abcc11`   | An integration partner resource could not be found.                                             |\n| `abdd11`   | The communication with the integration partner failed.                                          |\n| `abee11`   | Authorization with the integration partner failed.                                              |\n| `abfe11`   | The integration is not acceptable                                                               |\n| `abff11`   | The integration is disabled.                                                                    |\n"
  contact:
    name: Kisi Support
    email: support@getkisi.com
servers:
- url: https://api.kisi.io
  description: Kisi Production
tags:
- name: Readers
paths:
  /readers:
    get:
      operationId: fetchReaders
      summary: Fetch readers
      tags:
      - Readers
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: ids
        in: query
        schema:
          type: string
        description: Filter by object IDs
      - name: query
        in: query
        schema:
          type: string
        description: 'Filter by a freetext string. Properties searched: `name`, `device_id`, `token`

          '
      - name: model
        in: query
        schema:
          type: string
          enum:
          - reader-1.0
          - reader-2.0
          - reader-pro-2.1
          - reader-pro-2.1-hf
          - reader-pro-3.0
        description: Filter by model
      - name: place_id
        in: query
        schema:
          type: integer
        description: Filter by place ID
      - name: lock_id
        in: query
        schema:
          type: integer
        description: Filter by lock ID
      - name: limit
        in: query
        schema:
          type: integer
          default: 10
          maximum: 250
        description: The number of objects to return
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
          maximum: 20000
        description: The number of objects to offset
      - name: status
        in: query
        schema:
          type: string
          enum:
          - online
          - offline
        description: Filter by status
      - name: sort
        in: query
        schema:
          type: string
          enum:
          - name
          - -name
        description: 'Sort the results. Prepend `-` to sort in reverse order.


          `name` - sort by group name, alphabetically

          '
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  title: Reader
                  properties:
                    id:
                      type: integer
                      description: The ID of the reader
                    resource_type:
                      type: string
                      description: The resource type of the reader
                      const: Reader
                    name:
                      type: string
                      description: The name of the reader
                    description:
                      type:
                      - string
                      - 'null'
                      description: The description of the reader
                    created_at:
                      type: string
                      format: date-time
                      description: When the reader was created
                    updated_at:
                      type: string
                      format: date-time
                      description: When the reader was updated
                    broadcast_ip_address:
                      type:
                      - string
                      - 'null'
                      description: The broadcast IP address of the reader
                    configured:
                      type: boolean
                      description: Whether the reader is configured
                    device_id:
                      type: string
                      pattern: ^[a-fA-F0-9]{16}$
                      minLength: 16
                      maxLength: 16
                      description: 'The device ID of the reader

                        '
                    ethernet_mac:
                      type: string
                      description: The ethernet MAC address of the reader
                    gateway_ip_address:
                      type:
                      - string
                      - 'null'
                      description: The gateway IP address of the reader
                    ip_address:
                      type:
                      - string
                      - 'null'
                      description: The IP address of the reader
                    model:
                      type: string
                      enum:
                      - reader-1.0
                      - reader-2.0
                      - reader-pro-2.1
                      - reader-pro-2.1-hf
                      - reader-pro-3.0
                      description: The model of the reader
                    network_interface:
                      type:
                      - string
                      - 'null'
                      enum:
                      - ethernet
                      - wifi
                      - null
                      description: The network interface of the reader
                    network:
                      type:
                      - string
                      - 'null'
                      description: The network of the reader
                    online:
                      type: boolean
                      description: Whether the reader is online
                    revision:
                      type: string
                      description: The revision of the reader
                    token:
                      type: string
                      description: The token of the reader
                    wifi_mac:
                      type: string
                      description: The wifi MAC address of the reader
                    backplate:
                      type: string
                      enum:
                      - standard
                      - keypad_terminal
                      - quick_response_code_terminal
                      - keypad_and_quick_response_code_terminal
                      description: The backplate of the reader
                    buzzer_enabled:
                      type: boolean
                      description: Whether the reader is buzzer enabled
                    cards_enabled:
                      type: boolean
                      description: Whether the reader is cards enabled
                    checkout:
                      type: boolean
                      description: Whether the reader is checkout enabled
                    device_unlock_restriction_enabled:
                      type: boolean
                      description: 'Whether the reader is device unlock restriction enabled

                        '
                    held_open_alarm_enabled:
                      type: boolean
                      description: 'Whether the reader is held_open_alarm enabled"

                        '
                    quick_response_code_enabled:
                      type: boolean
                      description: Whether the reader is quick response code enabled
                    tampered:
                      type: boolean
                      description: Whether the reader is in a tampered state
                    tamper_enabled:
                      type: boolean
                      description: Whether the reader is tamper enabled
                    wave_to_unlock_enabled:
                      type: boolean
                      description: 'Whether the reader is wave to unlock enabled

                        '
                    elevator_id:
                      type:
                      - integer
                      - 'null'
                      description: The elevator ID of the reader
                    elevator:
                      type: object
                      title: Elevator
                      description: The elevator of the reader
                      properties:
                        id:
                          type: integer
                          description: The ID of the elevator
                        resource_type:
                          type: string
                          description: The resource type of the elevator
                          const: Elevator
                        name:
                          type: string
                          description: The name of the elevator
                      required:
                      - id
                      - resource_type
                      - name
                      additionalProperties: false
                    lock_id:
                      type:
                      - integer
                      - 'null'
                      description: The lock ID of the reader
                    lock:
                      type: object
                      title: Lock
                      description: The lock of the reader
                      properties:
                        id:
                          type: integer
                          description: The ID of the lock
                        resource_type:
                          type: string
                          description: The resource type of the lock
                          const: Lock
                        name:
                          type: string
                          description: The name of the lock
                      required:
                      - id
                      - resource_type
                      - name
                      additionalProperties: false
                    place_id:
                      type: integer
                      description: The place ID of the reader
                    place:
                      type: object
                      title: Place
                      description: The place of the reader
                      properties:
                        id:
                          type: integer
                          description: The ID of the place
                        resource_type:
                          type: string
                          description: The resource type of the place
                          const: Place
                        name:
                          type: string
                          description: The name of the place
                      required:
                      - id
                      - resource_type
                      - name
                      additionalProperties: false
                    zone_id:
                      type:
                      - integer
                      - 'null'
                      description: The zone ID of the reader
                    zone:
                      type: object
                      title: Zone
                      description: The zone of the reader
                      properties:
                        id:
                          type: integer
                          description: The ID of the zone
                        name:
                          type: string
                          description: The name of the zone
                      required:
                      - id
                      - name
                      additionalProperties: false
                    terminal_id:
                      type:
                      - integer
                      - 'null'
                      description: The terminal ID of the reader
                    terminal:
                      type: object
                      title: Terminal
                      description: The terminal of the reader
                      properties:
                        id:
                          type: integer
                          description: The ID of the terminal
                        resource_type:
                          type: string
                          description: The resource type of the terminal
                          const: Terminal
                        name:
                          type: string
                          description: The name of the terminal
                      required:
                      - id
                      - resource_type
                      - name
                      additionalProperties: false
                  required:
                  - id
                  - resource_type
                  - name
                  - description
                  - created_at
                  - updated_at
                  - broadcast_ip_address
                  - configured
                  - device_id
                  - ethernet_mac
                  - gateway_ip_address
                  - ip_address
                  - model
                  - network_interface
                  - network
                  - online
                  - revision
                  - token
                  - wifi_mac
                  - backplate
                  - buzzer_enabled
                  - cards_enabled
                  - checkout
                  - device_unlock_restriction_enabled
                  - held_open_alarm_enabled
                  - quick_response_code_enabled
                  - tampered
                  - tamper_enabled
                  - wave_to_unlock_enabled
                  - elevator_id
                  - lock_id
                  - place_id
                  - place
                  - zone_id
                  - terminal_id
                  additionalProperties: false
          headers:
            X-Collection-Range:
              description: 'Pagination information for offset based pagination. `start-end` represents the range

                of items requested. `total` represents the total count of items. If there is a total

                of 15 items and an offset of 10 and limit of 10 is used, the resulting header is:

                `10-19/15`.

                '
              schema:
                type: string
                pattern: ^(?<start>\d+)-(?<end>\d+)/(?<total>\d+)$
              example: 0-9/200
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /readers/{token}/assign:
    post:
      operationId: assignReader
      summary: Assign a reader by token
      tags:
      - Readers
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: token
        in: path
        schema:
          type: string
        description: The token of the reader.
        required: true
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: Reader
              properties:
                reader:
                  type: object
                  properties:
                    name:
                      type: string
                      description: The name of the reader
                    place_id:
                      type: integer
                      description: The place ID of the reader
                  required:
                  - name
                  - place_id
              required:
              - reader
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
  /readers/{id}/deassign:
    post:
      operationId: deassignReader
      summary: Deassign a reader
      tags:
      - Readers
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /readers/{id}/reset_tamper:
    post:
      operationId: resetTamperedState
      summary: Reset the tampered state of a reader
      tags:
      - Readers
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /readers/{id}/reboot:
    post:
      operationId: rebootReader
      summary: Reboot a reader
      tags:
      - Readers
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /readers/{id}:
    get:
      operationId: fetchReader
      summary: Fetch reader
      tags:
      - Readers
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: Reader
                properties:
                  id:
                    type: integer
                    description: The ID of the reader
                  resource_type:
                    type: string
                    description: The resource type of the reader
                    const: Reader
                  name:
                    type: string
                    description: The name of the reader
                  description:
                    type:
                    - string
                    - 'null'
                    description: The description of the reader
                  created_at:
                    type: string
                    format: date-time
                    description: When the reader was created
                  updated_at:
                    type: string
                    format: date-time
                    description: When the reader was updated
                  broadcast_ip_address:
                    type:
                    - string
                    - 'null'
                    description: The broadcast IP address of the reader
                  configured:
                    type: boolean
                    description: Whether the reader is configured
                  device_id:
                    type: string
                    pattern: ^[a-fA-F0-9]{16}$
                    minLength: 16
                    maxLength: 16
                    description: 'The device ID of the reader

                      '
                  ethernet_mac:
                    type: string
                    description: The ethernet MAC address of the reader
                  gateway_ip_address:
                    type:
                    - string
                    - 'null'
                    description: The gateway IP address of the reader
                  ip_address:
                    type:
                    - string
                    - 'null'
                    description: The IP address of the reader
                  model:
                    type: string
                    enum:
                    - reader-1.0
                    - reader-2.0
                    - reader-pro-2.1
                    - reader-pro-2.1-hf
                    - reader-pro-3.0
                    description: The model of the reader
                  network_interface:
                    type:
                    - string
                    - 'null'
                    enum:
                    - ethernet
                    - wifi

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kisi/refs/heads/main/openapi/kisi-readers-api-openapi.yml