KISI Event sets API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Kisi Calendars Event sets 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: Event sets
paths:
  /event_sets:
    post:
      operationId: createEventSet
      summary: Create event set
      description: 'This endpoint can be used to create an event set that can later be paginated through with a cursor. The set will be persisted and available for pagination for approximately 24 hours.


        When creating the event set the events may not be immediately available. Check the `status` property to determine if the events are available.

        - If `in_progress`, periodically check `GET /event_sets/{id}` until status is `finished`.

        - If `finished`, `events` will contain the events, and `cursor` will contain the cursor used to paginate the set.

        '
      tags:
      - Event sets
      security:
      - Kisi-Login: []
      - OAuth2: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              title: Event Set
              properties:
                event_set:
                  type: object
                  properties:
                    interval:
                      type: string
                      description: 'Filter by the creation date of the event. The timestamp is expected to be in ISO8601 format.


                        The interval defaults to the past 90 days. The interval cannot be wider than 90 days.


                        Supported patterns:

                        - Start/End, eg. `2019-03-09T13:00:00Z/2019-03-10T15:30:00Z`

                        - Start/Duration, eg. `2019-03-09T13:00:00Z/P1Y2M10D`

                        - Duration/End, eg. `PT2H30M/2019-03-09T15:30:00Z`


                        Duration on its own (eg. `P1Y2MT1H`) is not supported.

                        '
                    event_actor_id:
                      type:
                      - integer
                      - 'null'
                    event_actor_type:
                      type:
                      - string
                      - 'null'
                    event_authenticated_by_id:
                      type:
                      - integer
                      - 'null'
                    event_authenticated_by_type:
                      type:
                      - string
                      - 'null'
                    event_object_id:
                      type:
                      - integer
                      - 'null'
                    event_object_type:
                      type:
                      - string
                      - 'null'
                    event_place_id:
                      type:
                      - integer
                      - 'null'
                      description: The place ID to filter events by. Only one of event_place_id and place_id can be set.
                    event_success:
                      type:
                      - boolean
                      - 'null'
                    event_sequence:
                      type:
                      - string
                      - 'null'
                      description: Multiple sequences are separated with `,`
                    event_type:
                      type:
                      - string
                      - 'null'
                      description: Multiple types are separated with `,`
                    event_uuid:
                      type:
                      - string
                      - 'null'
                      description: Multiple UUIDs are separated with `,`
                    place_id:
                      type:
                      - integer
                      - 'null'
                      description: The place ID of a place-scoped event set. Only one of place_id and event_place_id can be set.
                  required: []
              required:
              - event_set
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: Event Set
                properties:
                  id:
                    type: integer
                    description: The ID of the event set
                  created_at:
                    type: string
                    format: date-time
                    description: When the event set was created
                  status:
                    type: string
                    enum:
                    - in_progress
                    - finished
                    - failed
                    description: The status of the event set
                  interval:
                    type: string
                    description: 'Filter by the creation date of the event. The timestamp is expected to be in ISO8601 format.


                      The interval defaults to the past 90 days. The interval cannot be wider than 90 days.


                      Supported patterns:

                      - Start/End, eg. `2019-03-09T13:00:00Z/2019-03-10T15:30:00Z`

                      - Start/Duration, eg. `2019-03-09T13:00:00Z/P1Y2M10D`

                      - Duration/End, eg. `PT2H30M/2019-03-09T15:30:00Z`


                      Duration on its own (eg. `P1Y2MT1H`) is not supported.

                      '
                  event_actor_id:
                    type:
                    - integer
                    - 'null'
                  event_actor_type:
                    type:
                    - string
                    - 'null'
                  event_authenticated_by_id:
                    type:
                    - integer
                    - 'null'
                  event_authenticated_by_type:
                    type:
                    - string
                    - 'null'
                  event_object_id:
                    type:
                    - integer
                    - 'null'
                  event_object_type:
                    type:
                    - string
                    - 'null'
                  event_place_id:
                    type:
                    - integer
                    - 'null'
                    description: The place ID to filter events by. Only one of event_place_id and place_id can be set.
                  event_success:
                    type:
                    - boolean
                    - 'null'
                  event_sequence:
                    type:
                    - string
                    - 'null'
                    description: Multiple sequences are separated with `,`
                  event_type:
                    type:
                    - string
                    - 'null'
                    description: Multiple types are separated with `,`
                  event_uuid:
                    type:
                    - string
                    - 'null'
                    description: Multiple UUIDs are separated with `,`
                  events:
                    type: array
                    items:
                      type: object
                      title: Event
                      properties:
                        uuid:
                          type: string
                          format: uuid
                          description: The UUID of the event
                        type:
                          type: string
                          description: The type of the event
                        actor_type:
                          type:
                          - string
                          - 'null'
                          enum:
                          - null
                          - GroupLink
                          - MarketplaceInstallation
                          - User
                          - Guest
                          description: The type of the actor of the event
                        actor_id:
                          type:
                          - integer
                          - 'null'
                          description: The ID of the actor of the event
                        actor_name:
                          type:
                          - string
                          - 'null'
                          description: The name of the actor of the event
                        actor_email:
                          type:
                          - string
                          - 'null'
                          description: The email of the actor of the event
                        authenticated_by_type:
                          type:
                          - string
                          - 'null'
                          enum:
                          - null
                          - ApplePassInstance
                          - Card
                          - GroupLink
                          - Login
                          - OauthAccessToken
                          - AccessKey
                          description: The type of the credential of the event
                        authenticated_by_id:
                          type:
                          - integer
                          - 'null'
                          description: The ID of the credential
                        authorized_by_type:
                          type:
                          - string
                          - 'null'
                        authorized_by_id:
                          type:
                          - integer
                          - 'null'
                        authorized_by_role_id:
                          type:
                          - string
                          - 'null'
                        object_type:
                          type: string
                          description: The type of the object of the event
                        object_id:
                          type: integer
                          description: The ID of the object of the event
                        object_name:
                          type: string
                          description: The name of the object of the event
                        object:
                          type: object
                          description: The object of the event
                        action:
                          type: string
                          description: The action of the event
                        created_at:
                          type: string
                          format: date-time
                          description: When the event was created
                        message:
                          type:
                          - string
                          - 'null'
                          description: The string representation of the event
                        success:
                          type: boolean
                          description: Whether the action was successful
                        code:
                          type:
                          - string
                          - 'null'
                          description: The code of the event
                        sequence:
                          type: string
                          description: The sequence used to group related events part of the same action
                        organization_id:
                          type: integer
                          description: The organization ID of the event
                        place_id:
                          type:
                          - integer
                          - 'null'
                          description: The place ID of the event
                        error_code:
                          type:
                          - string
                          - 'null'
                          description: The error code of the event
                        error_message:
                          type:
                          - string
                          - 'null'
                          description: The error message of the event
                        details:
                          deprecated: true
                          type: object
                        via:
                          deprecated: true
                          type: object
                      required:
                      - uuid
                      - type
                      - actor_type
                      - actor_id
                      - actor_name
                      - actor_email
                      - authenticated_by_type
                      - authenticated_by_id
                      - authorized_by_type
                      - authorized_by_id
                      - authorized_by_role_id
                      - object_type
                      - object_id
                      - object_name
                      - action
                      - created_at
                      - message
                      - success
                      - code
                      - sequence
                      - organization_id
                      - place_id
                      - error_code
                      - error_message
                      - details
                      - via
                      additionalProperties: false
                    description: The events of the event. Is not included if `status` is `in_progress`.
                  cursor:
                    type:
                    - string
                    - 'null'
                    description: The cursor of the event set. Will be `null` if `status` is `in_progress` or if there are no more events.
                  place_id:
                    type:
                    - integer
                    - 'null'
                    description: The place ID of a place-scoped event set. Only one of place_id and event_place_id can be set.
                required:
                - id
                - created_at
                - status
                - interval
                - event_actor_id
                - event_actor_type
                - event_authenticated_by_id
                - event_authenticated_by_type
                - event_object_id
                - event_object_type
                - event_place_id
                - event_success
                - event_sequence
                - event_type
                - event_uuid
                - cursor
                - place_id
                additionalProperties: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /event_sets/{id}:
    get:
      operationId: fetchEventSet
      summary: Fetch event set
      tags:
      - Event sets
      security:
      - Kisi-Login: []
      - OAuth2: []
      parameters:
      - name: id
        in: path
        schema:
          type: integer
        required: true
        description: The ID of the object
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
      - name: cursor
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                title: Event Set
                properties:
                  id:
                    type: integer
                    description: The ID of the event set
                  created_at:
                    type: string
                    format: date-time
                    description: When the event set was created
                  status:
                    type: string
                    enum:
                    - in_progress
                    - finished
                    - failed
                    description: The status of the event set
                  interval:
                    type: string
                    description: 'Filter by the creation date of the event. The timestamp is expected to be in ISO8601 format.


                      The interval defaults to the past 90 days. The interval cannot be wider than 90 days.


                      Supported patterns:

                      - Start/End, eg. `2019-03-09T13:00:00Z/2019-03-10T15:30:00Z`

                      - Start/Duration, eg. `2019-03-09T13:00:00Z/P1Y2M10D`

                      - Duration/End, eg. `PT2H30M/2019-03-09T15:30:00Z`


                      Duration on its own (eg. `P1Y2MT1H`) is not supported.

                      '
                  event_actor_id:
                    type:
                    - integer
                    - 'null'
                  event_actor_type:
                    type:
                    - string
                    - 'null'
                  event_authenticated_by_id:
                    type:
                    - integer
                    - 'null'
                  event_authenticated_by_type:
                    type:
                    - string
                    - 'null'
                  event_object_id:
                    type:
                    - integer
                    - 'null'
                  event_object_type:
                    type:
                    - string
                    - 'null'
                  event_place_id:
                    type:
                    - integer
                    - 'null'
                    description: The place ID to filter events by. Only one of event_place_id and place_id can be set.
                  event_success:
                    type:
                    - boolean
                    - 'null'
                  event_sequence:
                    type:
                    - string
                    - 'null'
                    description: Multiple sequences are separated with `,`
                  event_type:
                    type:
                    - string
                    - 'null'
                    description: Multiple types are separated with `,`
                  event_uuid:
                    type:
                    - string
                    - 'null'
                    description: Multiple UUIDs are separated with `,`
                  events:
                    type: array
                    items:
                      type: object
                      title: Event
                      properties:
                        uuid:
                          type: string
                          format: uuid
                          description: The UUID of the event
                        type:
                          type: string
                          description: The type of the event
                        actor_type:
                          type:
                          - string
                          - 'null'
                          enum:
                          - null
                          - GroupLink
                          - MarketplaceInstallation
                          - User
                          - Guest
                          description: The type of the actor of the event
                        actor_id:
                          type:
                          - integer
                          - 'null'
                          description: The ID of the actor of the event
                        actor_name:
                          type:
                          - string
                          - 'null'
                          description: The name of the actor of the event
                        actor_email:
                          type:
                          - string
                          - 'null'
                          description: The email of the actor of the event
                        authenticated_by_type:
                          type:
                          - string
                          - 'null'
                          enum:
                          - null
                          - ApplePassInstance
                          - Card
                          - GroupLink
                          - Login
                          - OauthAccessToken
                          - AccessKey
                          description: The type of the credential of the event
                        authenticated_by_id:
                          type:
                          - integer
                          - 'null'
                          description: The ID of the credential
                        authorized_by_type:
                          type:
                          - string
                          - 'null'
                        authorized_by_id:
                          type:
                          - integer
                          - 'null'
                        authorized_by_role_id:
                          type:
                          - string
                          - 'null'
                        object_type:
                          type: string
                          description: The type of the object of the event
                        object_id:
                          type: integer
                          des

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