openapi.yaml

openapi: 3.0.2
info:
  title: Akiles
  description: Akiles API
  contact:
    email: support@akiles.app
  version: "2.0"
servers:
  - url: https://api.akiles.app/v2
tags:
  - name: metadata
    x-spectacular-title: Metadata
    description: |
      Most API objects allow you to attach your own, arbitrary key-value metadata in the `metadata` field. You can use it to store references to primary keys of your database, custom states, etc.

      Metadata is visible to anyone with admin or API access to your organization. There is a storage limit of 1024 bytes of metadata per object.
  - name: organization
    x-spectacular-title: Organizations
    description: |
      Everything in Akiles APIs belongs to an Organization. An organization represents one Akiles customer and can handle multiple sites, gadgets, etc..
      Access tokens are tied to organizations too, and they give access only to the objects belonging to the organization.
  - name: site
    x-spectacular-title: Sites
    description: |
      A site is a physical place where Akiles gadgets are installed. For example, it can be a building, a floor... Gadgets belong to a particular site.

      End users will see one "card" in their app's home screen per site. The site information (email, contact, etc) is displayed in that card.
  - name: product
    x-spectacular-title: Products
  - name: device
    x-spectacular-title: Devices
    description: |
      Physical Akiles device installed in the organization.

      Each device has a set of capabilities which depend on the product.

      The `device` object also contains an overview of the current device status (online/offline, battery level).

      If `hardware_id = null`, the device is "virtual". It is designed for API testing: it behaves as close as possible to a real
      device in API calls but is not backed by a real hardware device. Gadget actions always succeed.
  - name: gadget
    x-spectacular-title: Gadgets
    description: |
      A gadget is a "thing that can be controlled" by the user. Gadgets can be doors, lights, heating, window blinds... 

      Gadgets are NOT physical devices. Some devices can have multiple gadgets because they have multiple inputs/outputs so
      they can control multiple things (Controllers).
      Others can have only one (the Cylinder and the Roomlock, for example). Others can have none (the Gateway Ethernet, for example.

      Gadgets can have multiple actions depending on what they are. For example, a normal
      door will just have an `open` action, but a blind\ncan have `raise` and `lower`
      actions, and a light can have `on` and `off` actions. Actions are identified
      by their string ID, and they\nalso have a human-friendly name for display in
      the UI.
  - name: member
    x-spectacular-title: Members
    description: ""
  - name: member_group
    x-spectacular-title: Member groups
    description: ""
  - name: schedule
    x-spectacular-title: Schedules
    description: ""
  - name: card
    x-spectacular-title: Cards
    description: "Cards configured for a particular organization"
  - name: event
    x-spectacular-title: Events
    description: |
      Everything that happens in an Akiles organization is logged as an Event.

      Events are structured in "subject - verb - object" form:

      - Subject: *who* did the action. It can be a member, an administrator, an OAuth application...
      - Verb: *what action* was done on the object. Create, edit, delete, use...
      - Object: *what object* the action was done on. A member, a gadget...

      For example:
      
      - gadget action events (i.e. someone opening a door) are reported with the member in the subject, `use` as verb, and the gadget action as object.
      - Member editions are reported with the admin user who did the action in the subject, `edit` as the verb, and the member as the object.

      ### Offline delayed events

      Gadget action events originate from the Akiles device when the user uses PINs, NFC cards or phone, or BT from a phone to open. If the Akiles device
      is offline (i.e. has no connection to Akiles Cloud), it buffers events in local persistent memory and reports them later when it
      becomes online again. When this happens, the event appears with the `created_at` corresponding to the moment it originally happened,
      NOT the moment when it was reported.

  - name: webhook
    x-spectacular-title: Webhooks
    description: |
      Webhooks allow your server to receive real-time notifications about events happening
      in the Akiles organization.

      Webhooks send a POST request to the indicated url when a matching event occurs. The request body is a JSON-encoded
      [event](#/components/schemas/event), same as you would get in the response of the ["get event" endpoint](#/operations/event_get).

      URL can be HTTP or HTTPS. We strongly recommend using HTTPS for production.

      ### Filtering

      Each webhook has a "filter" which specifies which events should be sent to it. A filter is a list of "filter rules". Each rule specifies:

      - `object_type`: The value of `object.type` to match. This must be specified, i.e. it's NOT possible to subscribe to all object types.
      - `verb`: The value of `verb` to match. If it's set to `null` it matches all verbs, i.e. it IS possible to subscribe to all events about one object type, all verbs.

      The webhook filter matches if any of the rules in the array match.

      Some examples:

      - `"filter": []`: Matches no events. Events match if at least one filter rule matches, which can't happen if there's no rules at all.
      - `"filter": [{"verb": "use", "object_type": "gadget_action"}]`: Matches gadget action events.
      - `"filter": [{"object_type": "member"}]`: Matches all events related to members (creation, edition, deletion...)
      - `"filter": [{"verb": "edit", "object_type": "member"}]`: Matches member edition events.
      - `"filter": [{"verb": "edit", "object_type": "member"}, {"verb": "use", "object_type": "gadget_action"}]`: Matches member editions, and gadget actions.

      An event will be sent to this webhook if it matches at least one rule. If it matches multiple rules, it will only be sent once. If it matches multiple webhook objects, it will be sent once per webhook to its respective URL, even if the URL is the same.

      ### Signature

      If an attacker learns the URL of your webhook, they could send requests themselves to it, spoofing webhooks.
      To prevent this, Akiles signs the webhook requests so that your server can check they come from Akiles and not
      an attacker. It's strongly recommended to verify the signature.

      The signature is the result of applying HMAC-SHA256 to the raw request body bytes, using the webhook secret as a key.
      It's sent in the `X-Akiles-Sig-SHA256` HTTP header.

      The secret is returned when you create the webhook. It's not possible to view the secret of an existing webhook,
      you have to delete and recreate it instead.

      The following is an example of how to receive webhooks and validate the signature using nodejs:

      ```js
      import url from 'url'
      import http from 'http'
      import crypto from 'crypto'

      // replace with the secret you get when creating the webhook.
      const webhookSecret = 'f305d484fd10de285b00bb203659e863';

      const app = http.createServer((request, response) => {
          let body = [];
          request.on('data', (chunk) => {
              body.push(chunk);
          }).on('end', () => {
              body = Buffer.concat(body).toString();

              const gotSig = Buffer.from(request.headers['x-akiles-sig-sha256'], 'hex');
              const expectedSig = crypto.createHmac("sha256", webhookSecret).update(body).digest();
              const ok = crypto.timingSafeEqual(gotSig, expectedSig);
              if (!ok) {
                  response.writeHead(400);
                  response.write('bad sig');
                  response.end();
                  return;
              }

              const event = JSON.parse(body.toString());
              console.log('Got event!');
              console.log(event);

              response.writeHead(200);
              response.write('cool');
              response.end();
          });
      });

      app.listen(8088);
      ```

      ### Delivery

      Webhook delivery is considered successful if your server returns a 2xx status code.

      Unsuccessful deliveries are retried, with an exponential backoff starting at a few seconds and
      doubling every time, for up to 1 hour.
paths:
  /organization:
    get:
      tags:
        - organization
      summary: Get organization
      operationId: organization_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/organization"
    patch:
      tags:
        - organization
      summary: Edit organization
      operationId: organization_edit
      requestBody:
        description: Member to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/organization"
  /sites:
    get:
      tags:
        - site
      summary: List sites
      operationId: site_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/site"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
  /sites/{site_id}:
    parameters:
      - name: site_id
        in: path
        description: site ID
        required: true
        schema:
          type: string
          format: site_id
    get:
      tags:
        - site
      summary: Get site
      operationId: site_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/site"
    patch:
      tags:
        - site
      summary: Edit site
      operationId: site_edit
      requestBody:
        description: Site to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/site"
  /products:
    get:
      tags:
        - product
      summary: List products
      operationId: product_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/product"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
  /products/{product_id}:
    parameters:
      - name: product_id
        in: path
        description: product ID
        required: true
        schema:
          type: string
          format: product_id
    get:
      tags:
        - product
      summary: Get product
      operationId: product_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/product"
  /devices:
    get:
      tags:
        - device
      summary: List devices
      operationId: device_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/device"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
  /devices/{device_id}:
    parameters:
      - name: device_id
        in: path
        description: device ID
        required: true
        schema:
          type: string
          format: device_id
    get:
      tags:
        - device
      summary: Get device
      operationId: device_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/device"
    patch:
      tags:
        - device
      summary: Edit device
      operationId: device_edit
      requestBody:
        description: Gadget to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/device"
  /gadgets:
    get:
      tags:
        - gadget
      summary: List gadgets
      operationId: gadget_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/gadget"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
  /gadgets/{gadget_id}:
    parameters:
      - name: gadget_id
        in: path
        description: gadget ID
        required: true
        schema:
          type: string
          format: gadget_id
    get:
      tags:
        - gadget
      summary: Get gadget
      operationId: gadget_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/gadget"
    patch:
      tags:
        - gadget
      summary: Edit gadget
      operationId: gadget_edit
      requestBody:
        description: Gadget to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/gadget"
  /gadgets/{gadget_id}/actions/{action_id}:
    parameters:
      - name: gadget_id
        in: path
        description: gadget ID
        required: true
        schema:
          type: string
          format: gadget_id
      - name: action_id
        in: path
        description: gadget action ID
        required: true
        schema:
          type: string
    post:
      tags:
        - gadget
      summary: Do gadget action
      description: This endpoint is only available to Akiles customers that have the whitelabel integration feature which has extra cost. If you want to make your integration public we recommend using the non whitelabel option.
      operationId: gadget_action
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example: {}
        required: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                example: {}
      x-codegen-request-body-name: body
  /events:
    get:
      tags:
        - event
      summary: List events
      operationId: event_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/event"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
  /events/{event_id}:
    parameters:
      - name: event_id
        in: path
        description: event ID
        required: true
        schema:
          type: string
          format: event_id
    get:
      tags:
        - event
      summary: Get event
      operationId: event_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/event"
  /members:
    get:
      tags:
        - member
      summary: List members
      operationId: member_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
        - $ref: "#/components/parameters/is_deleted"
        - name: email
          in: query
          description: Filter by email address
          required: false
          schema:
            type: string
            example: support@akiles.app
        - name: metadata.source
          in: query
          description: Filter by metadata.source
          required: false
          schema:
            type: string
        - name: metadata.sourceID
          in: query
          description: Filter by metadata.sourceID
          required: false
          schema:
            type: string

      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create member
      operationId: member_create
      requestBody:
        description: Member to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description:
                    Member name shown in the admin panel. This is for the organization
                    admins to identify the member, it's never shown to the user.
                  example: John Doe
                starts_at:
                  type: string
                  description:
                    Start date of the member's access. If null, the access is valid
                    immediately.
                  nullable: true
                  format: date-time
                ends_at:
                  type: string
                  description:
                    End date of the member's access. If null, the access is valid
                    forever (ie, until an end date is set or the member is deleted.)
                  nullable: true
                  format: date-time
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member"
  /members/{member_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: Get member
      operationId: member_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member"
    patch:
      tags:
        - member
      summary: Edit member
      operationId: member_edit
      requestBody:
        description: Member to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              required: []
              properties:
                name:
                  type: string
                  description:
                    Member name shown in the admin panel. This is for the organization
                    admins to identify the member, it's never shown to the user.
                  example: John Doe
                starts_at:
                  type: string
                  nullable: true
                  description:
                    Start date of the member's access. If null, the access is valid
                    immediately.
                  format: date-time
                ends_at:
                  type: string
                  nullable: true
                  description:
                    End date of the member's access. If null, the access is valid
                    forever (ie, until an end date is set or the member is deleted.)
                  format: date-time
                is_deleted:
                  type: boolean
                  description: True if this object has been deleted.
                  example: false
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member"
    delete:
      tags:
        - member
      summary: Delete member
      operationId: member_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member"

  /members/{member_id}/emails:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: List emails
      operationId: member_email_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_email"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create email
      operationId: member_email_create
      requestBody:
        description: Member email to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: Email address
                  format: email
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_email"
  /members/{member_id}/emails/{member_email_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_email_id
        in: path
        description: member email ID
        required: true
        schema:
          type: string
          format: member_email_id
    get:
      tags:
        - member
      summary: Get email
      operationId: member_email_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_email"
    patch:
      tags:
        - member
      summary: Edit email
      operationId: member_email_edit
      requestBody:
        description: Member email to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_email"
    delete:
      tags:
        - member
      summary: Delete email
      operationId: member_email_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_email"

  /members/{member_id}/magic_links:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: List magic links
      operationId: member_magic_link_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_magic_link"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create magic link
      operationId: member_magic_link_create
      requestBody:
        description: Member magic_link to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_magic_link_revealed"
  /members/{member_id}/magic_links/{member_magic_link_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_magic_link_id
        in: path
        description: member magic link ID
        required: true
        schema:
          type: string
          format: member_magic_link_id
    get:
      tags:
        - member
      summary: Get magic link
      operationId: member_magic_link_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_magic_link"
    patch:
      tags:
        - member
      summary: Edit magic link
      operationId: member_magic_link_edit
      requestBody:
        description: Member magic_link to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_magic_link"
    delete:
      tags:
        - member
      summary: Delete magic link
      operationId: member_magic_link_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_magic_link"
  /members/{member_id}/magic_links/{member_magic_link_id}/reveal:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_magic_link_id
        in: path
        description: member magic link ID
        required: true
        schema:
          type: string
          format: member_magic_link_id
    post:
      tags:
        - member
      summary: Reveal magic link
      operationId: member_magic_link_reveal
      requestBody:
        description: Empty JSON object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_magic_link_revealed"
  /members/{member_id}/pins:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: List pins
      operationId: member_pin_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_pin"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create pin
      description: |
        When creating a PIN, you can specify it in 3 ways depending on the fields you send in the request:

        - No fields: Akiles generates a random PIN, of the length configured in the organization's settings.
        - `length` only: Akiles generates a random PIN of the length you specify.
        - `pin` only: The PIN is the one you specify.

        The generated random PIN is included in the response.

        It is not allowed to have two (non-deleted) members with the same PIN in a given organization. For this
        reason, we recommend you let Akiles generate a random PIN instead of generating one yourself if you can
        (Akiles generates a PIN that is different to all existing members). If you specify the PIN directly, you
        have to ensure there's no PIN collisions yourself.
      operationId: member_pin_create
      requestBody:
        description: Member pin to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                length:
                  type: integer
                  description: Pin length. Optional (you can either not specify it, or set it to `null`).
                  example: 6
                pin:
                  type: string
                  description: Pin number. Optional (you can either not specify it, or set it to `null`).
                  example: "123456"
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_pin_revealed"
  /members/{member_id}/pins/{member_pin_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_pin_id
        in: path
        description: member pin ID
        required: true
        schema:
          type: string
          format: member_pin_id
    get:
      tags:
        - member
      summary: Get pin
      operationId: member_pin_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_pin"
    patch:
      tags:
        - member
      summary: Edit pin
      description: |
        NOTE: It is not possible to edit a MemberPin to change a PIN. Instead, delete it and create a new one.
      operationId: member_pin_edit
      requestBody:
        description: Member pin to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_pin"
    delete:
      tags:
        - member
      summary: Delete pin
      operationId: member_pin_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_pin"
  /members/{member_id}/pins/{member_pin_id}/reveal:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_pin_id
        in: path
        description: member pin ID
        required: true
        schema:
          type: string
          format: member_pin_id
    post:
      tags:
        - member
      summary: Reveal pin
      operationId: member_pin_reveal
      requestBody:
        description: Empty JSON object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_pin_revealed"
  /members/{member_id}/cards:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: List cards
      operationId: member_card_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_card"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create card
      operationId: member_card_create
      requestBody:
        description: Member card to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                card_id:
                  type: string
                  description: Card ID. Optional. One of `card_id`, `printed_code` or `uid` must be present.
                  format: card_id
                printed_code:
                  type: string
                  description: Unique code physically printed on the card. Optional. One of `card_id`, `printed_code` or `uid` must be present.
                  example: WHJSA
                uid:
                  type: string
                  description: ISO14443 UID for the card. Always 4, 7 or 10 bytes, encoded in hex. Optional. One of `card_id, `printed_code` or `uid` must be present.
                  example: 041E53F2FF6780
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_card"
  /members/{member_id}/cards/{member_card_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_card_id
        in: path
        description: member card ID
        required: true
        schema:
          type: string
          format: member_card_id
    get:
      tags:
        - member
      summary: Get card
      operationId: member_card_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_card"
    patch:
      tags:
        - member
      summary: Edit card
      operationId: member_card_edit
      requestBody:
        description: Member card to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_card"
    delete:
      tags:
        - member
      summary: Delete card
      operationId: member_card_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_card"
  /members/{member_id}/tokens:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: List tokens
      operationId: member_token_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_token"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create token
      operationId: member_token_create
      requestBody:
        description: Member token to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_token_revealed"
  /members/{member_id}/tokens/{member_token_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_token_id
        in: path
        description: member token ID
        required: true
        schema:
          type: string
          format: member_token_id
    get:
      tags:
        - member
      summary: Get token
      operationId: member_token_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_token"
    patch:
      tags:
        - member
      summary: Edit token
      operationId: member_token_edit
      requestBody:
        description: Member token to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_token"
    delete:
      tags:
        - member
      summary: Delete token
      operationId: member_token_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_token"
  /members/{member_id}/tokens/{member_token_id}/reveal:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_token_id
        in: path
        description: member token ID
        required: true
        schema:
          type: string
          format: member_token_id
    post:
      tags:
        - member
      summary: Reveal token
      operationId: member_token_reveal
      requestBody:
        description: Empty JSON object
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_token_revealed"
  /members/{member_id}/group_associations:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
    get:
      tags:
        - member
      summary: List group associations
      operationId: member_group_association_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_group_association"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member
      summary: Create group association
      operationId: member_group_association_create
      requestBody:
        description: Member group_association to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                member_group_id:
                  type: string
                  description: member_group ID
                  format: member_group_id
                starts_at:
                  type: string
                  nullable: true
                  description:
                    Start date of the member's access. If null, the access is valid
                    immediately.
                  format: date-time
                ends_at:
                  type: string
                  nullable: true
                  description:
                    End date of the member's access. If null, the access is valid
                    forever (ie, until an end date is set or the member is deleted.)
                  format: date-time
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group_association"
  /members/{member_id}/group_associations/{member_group_association_id}:
    parameters:
      - name: member_id
        in: path
        description: member ID
        required: true
        schema:
          type: string
          format: member_id
      - name: member_group_association_id
        in: path
        description: member group association ID
        required: true
        schema:
          type: string
          format: member_group_association_id
    get:
      tags:
        - member
      summary: Get group association
      operationId: member_group_association_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group_association"
    patch:
      tags:
        - member
      summary: Edit group association
      operationId: member_group_association_edit
      requestBody:
        description: Member group_association to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                starts_at:
                  type: string
                  nullable: true
                  description:
                    Start date of the member's access. If null, the access is valid
                    immediately.
                  format: date-time
                ends_at:
                  type: string
                  nullable: true
                  description:
                    End date of the member's access. If null, the access is valid
                    forever (ie, until an end date is set or the member is deleted.)
                  format: date-time
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group_association"
    delete:
      tags:
        - member
      summary: Delete group association
      operationId: member_group_association_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group_association"

  /cards:
    get:
      tags:
        - card
      summary: List cards
      operationId: card_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/card"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - card
      summary: Create card
      operationId: card_create
      requestBody:
        description: Card to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Card ID. Optional. One of `id`, `printed_code` or `uid` must be present.
                  format: card_id
                printed_code:
                  type: string
                  description: Unique code physically printed on the card. Optional. One of `id`, `printed_code` or `uid` must be present.
                  example: WHJSA
                uid:
                  type: string
                  description: ISO14443 UID for the card. Always 4, 7 or 10 bytes, encoded in hex. Optional. One of `id`, `printed_code` or `uid` must be present.
                  example: 041E53F2FF6780
                name:
                  type: string
                  description: Card name. Optional.
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/card"
  /cards/{card_id}:
    get:
      tags:
        - card
      operationId: card_get
      summary: Get cards
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/card"
    patch:
      tags:
        - card
      summary: Edit card
      operationId: card_edit
      requestBody:
        description: Card to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Card name
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
    delete:
      tags:
        - card
      summary: Delete card
      operationId: card_delete
      responses:
        200:
          description: Success

  /member_groups:
    get:
      tags:
        - member_group
      summary: List member groups
      operationId: member_group_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/member_group"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - member_group
      summary: Create member group
      operationId: member_group_create
      requestBody:
        description: Member group to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Group name
                permissions:
                  description:
                    Permission rules granted to members of this group. A member can have
                    multiple groups, and the permissions are the union of all the groups. Access
                    is granted if at least one rule matches.
                  type: array
                  items:
                    $ref: "#/components/schemas/member_group_permission_rule"
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group"
  /member_groups/{member_group_id}:
    parameters:
      - name: member_group_id
        in: path
        description: member_group ID
        required: true
        schema:
          type: string
          format: member_group_id
    get:
      tags:
        - member_group
      summary: Get member group
      operationId: member_group_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group"
    patch:
      tags:
        - member_group
      summary: Edit member group
      operationId: member_group_edit
      requestBody:
        description: Member group to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Group name
                permissions:
                  description:
                    Permission rules granted to members of this group. A member can have
                    multiple groups, and the permissions are the union of all the groups. Access
                    is granted if at least one rule matches.
                  type: array
                  items:
                    $ref: "#/components/schemas/member_group_permission_rule"
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group"
    delete:
      tags:
        - member_group
      summary: Delete member group
      operationId: member_group_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/member_group"

  /schedules:
    get:
      tags:
        - schedule
      summary: List schedules
      operationId: schedule_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/q"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/schedule"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - schedule
      summary: Create schedule
      operationId: schedule_create
      requestBody:
        description: schedule to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name
                weekdays:
                  description: |
                    Array of length 7 containing the time ranges for each weekday. Week starts on Monday, i.e. index 0 is Monday and index 6 is Sunday.

                    User is granted access according to the schedule if the current time (in the site's local time zone) falls within one of the specified ranges.

                    Range start and end are specified in number of seconds starting from 00:00. Start and end must be between 0 and 86400. End must be greater than start. Ranges within a single day must not overlap.
                  type: array
                  items:
                    type: object
                    properties:
                      ranges:
                        type: array
                        items:
                          type: object
                          properties:
                            start:
                              type: number
                            end:
                              type: number
                  example:
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: []}
                  - {ranges: []}
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/schedule"
  /schedules/{schedule_id}:
    parameters:
      - name: schedule_id
        in: path
        description: schedule ID
        required: true
        schema:
          type: string
          format: schedule_id
    get:
      tags:
        - schedule
      summary: Get schedule
      operationId: schedule_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/schedule"
    patch:
      tags:
        - schedule
      summary: Edit schedule
      operationId: schedule_edit
      requestBody:
        description: schedule to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name
                weekdays:
                  description: |
                    Array of length 7 containing the time ranges for each weekday. Week starts on Monday, i.e. index 0 is Monday and index 6 is Sunday.

                    User is granted access according to the schedule if the current time (in the site's local time zone) falls within one of the specified ranges.

                    Range start and end are specified in number of seconds starting from 00:00. Start and end must be between 0 and 86400. End must be greater than start. Ranges within a single day must not overlap.
                  type: array
                  items:
                    type: object
                    properties:
                      ranges:
                        type: array
                        items:
                          type: object
                          properties:
                            start:
                              type: number
                            end:
                              type: number
                  example:
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: [{start: 32400, end: 64800}]}
                  - {ranges: []}
                  - {ranges: []}
                metadata:
                  $ref: "#/components/schemas/metadata"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/schedule"
    delete:
      tags:
        - schedule
      summary: Delete schedule
      operationId: schedule_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/schedule"

  /webhooks:
    get:
      tags:
        - webhook
      summary: List webhooks
      operationId: webhook_list
      parameters:
        - $ref: "#/components/parameters/cursor"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/sort"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/webhook"
                  has_next:
                    type: boolean
                    example: true
                  cursor_next:
                    type: string
                    format: cursor
    post:
      tags:
        - webhook
      summary: Create webhook
      operationId: webhook_create
      requestBody:
        description: Webhook to create
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  description: Array of event filter rules.
                  type: array
                  items:
                    $ref: "#/components/schemas/webhook_filter_rule"
                  example: [{ object_type: gadget_action }]
                url:
                  type: string
                  description: URL the events are sent to.
                  example: https://example.com/hook
                is_enabled:
                  type: boolean
                  description: True if this webhook is enabled. When false, no webhooks are sent.
                  example: true
              required:
                - url
                - is_enabled
                - filter
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/webhook"
  /webhooks/{webhook_id}:
    parameters:
      - name: webhook_id
        in: path
        description: webhook ID
        required: true
        schema:
          type: string
          format: webhook_id
    get:
      tags:
        - webhook
      summary: Get webhook
      operationId: webhook_get
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/webhook"
    patch:
      tags:
        - webhook
      summary: Edit webhook
      operationId: webhook_edit
      requestBody:
        description: Webhook to edit
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filter:
                  description: Array of event filter rules.
                  type: array
                  items:
                    $ref: "#/components/schemas/webhook_filter_rule"
                  example: [{ object_type: gadget_action }]
                url:
                  type: string
                  description: URL the events are sent to.
                  example: https://example.com/hook
                is_enabled:
                  type: boolean
                  description: True if this webhook is enabled. When false, no webhooks are sent.
                  example: true
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/webhook"
    delete:
      tags:
        - webhook
      summary: Delete webhook
      operationId: webhook_delete
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/webhook"

security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    metadata:
      type: object
      x-spectacular-tags:
        - metadata
      additionalProperties:
        type: string
      example: { "key1": "value1", "key2": "value2" }
      description: Key-value metadata
    organization:
      type: object
      x-spectacular-tags:
        - organization
      properties:
        id:
          type: string
          description: Unique identifier.
          format: organization_id
        name:
          type: string
          description: Name.
          example: SkyCowork
        is_deleted:
          type: boolean
          description: Indicates if the object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
    location:
      x-spectacular-tags:
        - site
      type: object
      properties:
        lat:
          type: number
          description: Latitude in degrees
          format: float
          example: 41.290485
        lng:
          type: number
          description: Longitude
          format: float
          example: 2.1829076
    site_geo:
      type: object
      x-spectacular-tags:
        - site
      properties:
        location:
          $ref: "#/components/schemas/location"
        radius:
          type: number
          description: Radius in meters
          example: 100.0
    site_map:
      type: object
      x-spectacular-tags:
        - site
      properties:
        location:
          $ref: "#/components/schemas/location"
        place_id:
          type: string
          description: place_id from Google Maps Places API
        address:
          type: string
          description: Human-readable address
        image_url:
          type: string
          description: Map image URL, displayed in the site's header in the app.
    site:
      type: object
      x-spectacular-tags:
        - site
      properties:
        id:
          type: string
          description: site ID
          format: site_id
        name:
          type: string
          description: Site name
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        geo:
          $ref: "#/components/schemas/site_geo"
        map:
          $ref: "#/components/schemas/site_map"
        phone:
          type: string
          description: Phone number. Shown in the site info in the app.
        email:
          type: string
          description: Email. Shown in the site info in the app.
        info:
          type: string
          description: Free-form extra information. Shown in the site info in the app.
        timezone:
          type: string
          format: timezone
          example: "Europe/Madrid"
          description: Local time zone of the site.
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
    product:
      type: object
      x-spectacular-tags:
        - product
      properties:
        id:
          type: string
          description: product ID
          example: controller_ethernet
        name:
          type: string
          description: Human-friendly product name. Show this to the user instead of the product ID!
          example: Controller Ethernet
    device:
      type: object
      x-spectacular-tags:
        - device
      properties:
        id:
          type: string
          description: device ID
          format: device_id
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        name:
          type: string
          description: Device name
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        site_id:
          type: string
          description: site ID
          format: site_id
        hardware_id:
          type: string
          description: Hardware ID. This is the serial number printed in the device's label, as a QR and in some products as text.
          format: hardware_id
        metadata:
          $ref: "#/components/schemas/metadata"
        product_id:
          type: string
          description: "Product ID. NOTE: do not show this to the user directly, it's not capitalized properly. Use the `name` field from the `product` object instead."
          example: "controller_ethernet"
        revision_id:
          type: string
          description: "Hardware revision ID."
          example: "06"
        input_rules:
          type: array
          description: "Input rule array. Input rules configure a device to remotely trigger gadget actions on other devices remotely when the user inputs a PIN or an NFC card. Must be empty if `capabilities.input_rules = false`"
          items:
            $ref: "#/components/schemas/device_input_rule"
        capabilities:
          $ref: "#/components/schemas/device_capabilities"
        status:
          $ref: "#/components/schemas/device_status"
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
    device_capabilities:
      type: object
      x-spectacular-tags:
        - device
      description: "Device capabilities."
      properties:
        gadgets:
          type: string
          description: What level of gadget support this device has. `none` means it can't have gadgets, `single` means it MUST have exactly one gadget (not zero), `multiple` means it can have any (0..max).
          enum:
            - none
            - single
            - multiple
          example: multiple
        gadget_max_count:
          type: integer
          description: Maximum amount of gadgets the device supports. Will always be `0` if `gadgets="none"`, and `1` if `gadgets="single"`.
          example: 6
        script:
          type: boolean
          description: Whether this device supports gadgets with custom scripts.
          example: true
        internet:
          type: boolean
          description: Whether this device supports some form of internet connection, which means it can connect to Akiles Cloud directly instead of through gateways.
          example: true
        ethernet:
          type: boolean
          description: Whether this device supports Ethernet.
          example: true
        wifi:
          type: boolean
          description: Whether this device supports WiFi.
          example: false
        cellular:
          type: boolean
          description: Whether this device supports cellular internet.
          example: false
        pin:
          type: boolean
          description: Whether this device supports PIN entry (i.e. has a keypad).
          example: false
        nfc:
          type: boolean
          description: Whether this device supports NFC (either physical cards, or emulated cards in a phone)
          example: false
        input_rules:
          type: boolean
          description: Whether this device supports input rules.
          example: false
        mains:
          type: boolean
          description: Whether this device supports being powered from mains (either directly or with an AC adapter).
          example: true
        battery:
          type: boolean
          description: Whether this device supports being powered by batteries (rechargeable or not). It is possible for both `mains` and `battery` be `true` at the same time, this means the device can be powered from mains or from a battery or both (if both are present it will give preference to mains and use the battery as a backup).
          example: true
        battery_rechargeable:
          type: boolean
          description: If true, this device contains a rechargeable battery, and can recharge it from mains power.
          example: true
        audio:
          type: boolean
          description: If true, this device is equipped with a buzzer capable of emitting sounds for interactions and status updates.
          example: true
    device_status:
      type: object
      x-spectacular-tags:
        - device
      description: "Device status."
      properties:
        online:
          type: boolean
          description: True if this device is online (meaning it's on and has a working connection to Akiles Cloud, either directly or through gateways).
          example: true
        mains_present:
          type: boolean
          description: True if this device currently has mains power.
          example: true
        battery_present:
          type: boolean
          description: True if this device currently has a battery inserted.
          example: true
        battery_charging:
          type: boolean
          description: True if this device currently is charging the battery from mains power.
          example: true
        battery_percent:
          type: number
          description: Battery percentage, 0-100.
          example: 87.2
    device_input_rule:
      type: object
      description: |
        Input rules allow configuring "codes" that act as prefixes for PINs or cards. This allows a single device to 
        - Trigger different gadgets (local or remote).
        - Trigger different actions in a gadget.
        - Mix local and remote gadgets. One input rule can point to a local gadget (in this device), and another to a remote gadget (in another device, will be triggered via AkilesNet).

        Example:

        ```json
        "input_rules": [
            {
                "code": "1",
                "gadget_id": "gad_3z4f8pubhdcj2fvfmkxh", // street
                "action_id": "open"
            },
            {
                "code": "2",
                "gadget_id": "gad_3z4f8s623va4l9nea7u1", // garage door
                "action_id": "up"
            },
            {
                "code": "3",
                "gadget_id": "gad_3z4f8s623va4l9nea7u1", // garage door
                "action_id": "down"
            },
            {
                "code": "4",
                "gadget_id": "gad_3z4f8s623va4l9nea7u1", // garage door
                "action_id": "stop"
            }
        ]
        ```

        Typing "1" and your PIN, or typing "1" and tapping your card/phone would open the street door. Same with "2" would move the garage door up, "3" down, etc.

        Keypad rule codes accept digits 0-9, hash `#` and star `*`.

        You can define one keypad rule as the "default" one by setting the code to `""`. This is the rule that will be triggered if you type a PIN or tap a card directly without typing anything before. A default rule can coexist with other rules at the same time, but then all the other rules can't start with a digit (only with `*` or `#`), because it'd otherwise be ambiguous whether the user is typing a rule code or a PIN.

        If no input rules are defined (`input_rules` is an empty array), pins/cards will open the first action of the first gadget in the current device.
      x-spectacular-tags:
        - device
      properties:
        code:
          type: string
          description: Keypad code prefix. String consisting of digits 0-9, pound (`#`) and star (`*`). Can be empty, in which case this input rule is the default. If there is one input rule with empty code, the others must not start with a digit. To avoid ambiguity, no input rule can have a code that is the prefix of another one.
          example: '*2'
        gadget_id:
          type: string
          description: Destination gadget ID. It can be a gadget on this device, or on another device.
          format: gadget_id
        action_id:
          type: string
          description: Destination action ID. It must be a valid action in the destination gadget.
          example: 'open'
    gadget_action:
      type: object
      x-spectacular-tags:
        - gadget
      properties:
        id:
          type: string
          description: action ID
          example: open
        name:
          type: string
          description: Action user-friendly name
          example: Open
    gadget:
      type: object
      x-spectacular-tags:
        - gadget
      properties:
        id:
          type: string
          description: gadget ID
          format: gadget_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        site_id:
          type: string
          description: site ID
          format: site_id
        device_id:
          type: string
          description: device ID
          format: device_id
        name:
          type: string
          description: Gadget name
        actions:
          type: array
          items:
            $ref: "#/components/schemas/gadget_action"
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
    member_group:
      type: object
      x-spectacular-tags:
        - member_group
      properties:
        id:
          type: string
          description: member_group ID
          format: member_group_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        name:
          type: string
          description: Group name
        permissions:
          description:
            Permission rules granted to members of this group. A member can have
            multiple groups, and the permissions are the union of all the groups. Access
            is granted if at least one rule matches.
          type: array
          items:
            $ref: "#/components/schemas/member_group_permission_rule"
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
    card:
      type: object
      x-spectacular-tags:
        - card
      properties:
        id:
          type: string
          description: card ID
          format: card_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        name:
          type: string
          description: Card name in organization.
        uid:
          type: string
          description: ISO14443 UID for the card. Always 4, 7 or 10 bytes, encoded in hex.
          example: 041E53F2FF6780
        printed_code:
          type: string
          description: Unique code physically printed on the card.
          example: WHJSA
        metadata:
          $ref: "#/components/schemas/metadata"
    schedule:
      type: object
      x-spectacular-tags:
        - schedule
      properties:
        id:
          type: string
          description: schedule ID
          format: schedule_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        name:
          type: string
          description: Name
          example: Mon-Fri 9AM-6PM
        weekdays:
          description: |
            Array of length 7 containing the time ranges for each weekday. Week starts on Monday, i.e. index 0 is Monday and index 6 is Sunday.

            User is granted access according to the schedule if the current time (in the site's local time zone) falls within one of the specified ranges.

            Range start and end are specified in number of seconds starting from 00:00. Start and end must be between 0 and 86400. End must be greater than start. Ranges within a single day must not overlap.
          type: array
          items:
            type: object
            properties:
              ranges:
                type: array
                items:
                  type: object
                  properties:
                    start:
                      type: number
                    end:
                      type: number
          example:
          - {ranges: [{start: 32400, end: 64800}]}
          - {ranges: [{start: 32400, end: 64800}]}
          - {ranges: [{start: 32400, end: 64800}]}
          - {ranges: [{start: 32400, end: 64800}]}
          - {ranges: [{start: 32400, end: 64800}]}
          - {ranges: []}
          - {ranges: []}
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
    member_group_permission_rule:
      type: object
      x-spectacular-tags:
        - member_group
      description: |
        Rule granting permissions to a member group. Examples:
        - `{}` matches all gadgets in all sites
        - `{"site_id": "site_3merk33gt21kym11een1"}` matches all gadgets in that site.
        - `{"gadget_id": "gad_3merk33gt1hnl6pvbu71"}` matches that gadget only.

        It is not allowed to set `site_id` and `gadget_id` at the same time.
      properties:
        site_id:
          type: string
          description: Site ID. If set, the rule only matches gadgets in this site.
          format: site_id
        gadget_id:
          type: string
          description: Gadget ID. If set, the rule only matches this gadget.
          format: gadget_id
        action_id:
          type: string
          description: |
            Action ID. If set, the rule only matches this particular action within the gadget.

            Only one action can be chosen. If you want to allow multiple actions in the same gadget, create one permission rule for each action.

            If you set this, `gadget_id` must be set. That is, it's not possible to have a permission rule like "All gadgets in site X, but only action Y".
        schedule_id:
          type: string
          description:
            Schedule ID. If set, the rule only matches if the current time is
            within the schedule.
          format: schedule_id
        presence:
          type: string
          enum:
            - none
            - gps
          description: |
            Presence check performed. 
            - `none`: no presence check is done, the user can perform gadget actions using the
              Akiles app remotely, from anywhere in the world.
            - `gps`: the user must be within the site's GPS radius to perform gadget actions.

            Actions via PINs, cards and Bluetooth are always allowed and not affected by this setting.
        access_methods:
          type: object
          description: |
            Allowed access methods.
            - `online`: can be opened via Akiles Cloud.
            - `bluetooth`: can be opened via Bluetooth.
            - `mobile_nfc`: can be opened via NFC on phones.
            - `pin`: can be opened using a pin.
            - `card`: can be opened using a NFC card.
          properties:
            online:
              type: boolean
              description: Can be opened via Akiles Cloud.
            bluetooth:
              type: boolean
              description: Can be opened via Bluetooth.
            mobile_nfc:
              type: boolean
              description: Can be opened via NFC on phones.
            pin:
              type: boolean
              description: Can be opened using a pin.
            card:
              type: boolean
              description: Can be opened using a NFC card.

    member:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member ID
          format: member_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        name:
          type: string
          description:
            Member name shown in the admin panel. This is for the organization
            admins to identify the member, it's never shown to the user.
          example: John Doe
        starts_at:
          type: string
          nullable: true
          description:
            Start date of the member's access. If null, the access is valid
            immediately.
          format: date-time
        ends_at:
          type: string
          nullable: true
          description:
            End date of the member's access. If null, the access is valid
            forever (ie, until an end date is set or the member is deleted.)
          format: date-time
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - name
        - starts_at
        - ends_at
        - is_deleted
        - metadata
    member_email:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member email ID
          format: member_email_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        email:
          type: string
          description: Email address
          format: email_address
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - member_id
        - email
    member_magic_link:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member magic link ID
          format: member_magic_link_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - member_id
    member_magic_link_revealed:
      type: object
      x-spectacular-tags:
        - member
      properties:
        link:
          type: string
          format: url
          description: Magic link for this member. The guest will be able to use Akiles instantly by clicking it.
          example: https://link.akiles.app/#ml_8502850982345_f00i1nslz20gkm
        id:
          type: string
          description: member magic link ID
          format: member_magic_link_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - link
        - id
        - organization_id
        - member_id
    member_pin:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member pin ID
          format: member_pin_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        length:
          type: integer
          description: Pin length
          example: 6
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - member_id
    member_pin_revealed:
      type: object
      x-spectacular-tags:
        - member
      properties:
        pin:
          type: string
          description: Pin number.
          example: "123456"
        id:
          type: string
          description: member pin ID
          format: member_pin_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        length:
          type: integer
          description: Pin length
          example: 6
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - pin
        - id
        - organization_id
        - member_id
    member_card:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member card ID
          format: member_card_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        card_id:
          type: string
          description: card ID
          format: card_id
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - member_id
        - card_id
    member_token:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member token ID
          format: member_token_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - member_id
    member_token_revealed:
      type: object
      x-spectacular-tags:
        - member
      properties:
        token:
          type: string
          description: The token.
          example: "mt_3yd55tbrelfxhjjvkdqh_e39adeac25cdbd99c757124d70acb8b028bb471d8a2eebbc"
        id:
          type: string
          description: member token ID
          format: member_token_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - token
        - id
        - organization_id
        - member_id
    member_group_association:
      type: object
      x-spectacular-tags:
        - member
      properties:
        id:
          type: string
          description: member group association ID
          format: member_group_association_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        member_id:
          type: string
          description: member ID
          format: member_id
        member_group_id:
          type: string
          description: member_group ID
          format: member_group_id
        starts_at:
          type: string
          nullable: true
          description:
            Start date of the member's access. If null, the access is valid
            immediately.
          format: date-time
        ends_at:
          type: string
          nullable: true
          description:
            End date of the member's access. If null, the access is valid
            forever (ie, until an end date is set or the member is deleted.)
          format: date-time
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
        metadata:
          $ref: "#/components/schemas/metadata"
      required:
        - id
        - organization_id
        - member_id
        - member_group_id
    event:
      type: object
      x-spectacular-tags:
        - event
      properties:
        id:
          type: string
          description: event ID
          format: event_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        subject:
          $ref: "#/components/schemas/event_subject"
        verb:
          type: string
          example: use
          enum:
            - create
            - edit
            - delete
            - use
        object:
          $ref: "#/components/schemas/event_object"
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
    event_subject:
      type: object
      x-spectacular-tags:
        - event
      properties:
        member_id:
          type: string
          nullable: true
          description: 	member ID
          format: member_id
        member_email_id:
          type: string
          nullable: true
          description: 	member_email ID
          format: member_email_id
        member_magic_link_id:
          type: string
          nullable: true
          description: 	member_magic_link ID
          format: member_magic_link_id
        member_pin_id:
          type: string
          nullable: true
          description: 	member_pin ID
          format: member_pin_id
        member_card_id:
          type: string
          nullable: true
          description: 	member_card ID
          format: member_card_id
        member_token_id:
          type: string
          nullable: true
          description: 	member_token ID
          format: member_token_id
    event_object:
      type: object
      x-spectacular-tags:
        - event
      properties:
        type:
          type: string
          example: gadget_action
          enum:
          - device
          - gadget
          - gadget_action
          - member
          - member_email
          - member_magic_link
          - member_group
          - member_group_association
          - member_pin
          - member_card
          - member_token
          - organization
          - site
          - webhook
          - hardware
          - card
        device_id:
          type: string
          nullable: true
          description: device ID
          format: device_id
        gadget_id:
          type: string
          nullable: true
          description: gadget ID
          format: gadget_id
        gadget_action_id:
          type: string
          nullable: true
          description: gadget_action ID
          example: open
        member_id:
          type: string
          nullable: true
          description: member ID
          format: member_id
        member_email_id:
          type: string
          nullable: true
          description: member_email ID
          format: member_email_id
        member_magic_link_id:
          type: string
          nullable: true
          description: member_magic_link ID
          format: member_magic_link_id
        member_group_id:
          type: string
          nullable: true
          description: member_group ID
          format: member_group_id
        member_group_association_id:
          type: string
          nullable: true
          description: member_group_association ID
          format: member_group_association_id
        member_pin_id:
          type: string
          nullable: true
          description: member_pin ID
          format: member_pin_id
        member_card_id:
          type: string
          nullable: true
          description: member_card ID
          format: member_card_id
        member_token_id:
          type: string
          nullable: true
          description: member_token ID
          format: member_token_id
        organization_id:
          type: string
          nullable: true
          description: organization ID
          format: organization_id
        site_id:
          type: string
          nullable: true
          description: site ID
          format: site_id
        webhook_id:
          type: string
          nullable: true
          description: webhook ID
          format: webhook_id
        hardware_id:
          type: string
          nullable: true
          description: hardware ID
          format: hardware_id
        card_id:
          type: string
          nullable: true
          description: card ID
          format: card_id
    webhook_filter_rule:
      x-spectacular-tags:
        - webhook
      type: object
      properties:
        object_type:
          type: string
          description: Object type of the event.
          enum:
            - gadget
            - gadget_action
            - member
            - member_group
            - organization
            - site
        verb:
          type: string
          nullable: true
          description: Action verb of the event. If null, matches all verbs.
          enum:
            - create
            - edit
            - delete
            - use
      example: { object_type: gadget_action, verb: use }
    webhook:
      x-spectacular-tags:
        - webhook
      type: object
      properties:
        id:
          type: string
          description: webhook ID
          format: webhook_id
        organization_id:
          type: string
          description: organization ID
          format: organization_id
        filter:
          description: Array of event filter rules. An event will be sent to this webhook if it matches at least one rule. If it matches multiple rules, it will only be sent once. If it matches multiple webhook objects, it will be sent once per webhook to its respective URL.
          type: array
          items:
            $ref: "#/components/schemas/webhook_filter_rule"
        url:
          type: string
          description: URL the events are sent to.
          example: https://example.com/hook
        secret:
          type: string
          description: Secret used to sign webhooks. Visible only in the response for the creation API call.
          example: f305d484fd10de285b00bb203659e863
        is_enabled:
          type: boolean
          description: True if this webhook is enabled. When false, no webhooks are sent.
          example: true
        is_deleted:
          type: boolean
          description: True if this object has been deleted.
          example: false
        created_at:
          type: string
          description: Creation time for this object.
          format: date-time
      required:
        - id
        - organization_id
        - url
        - is_enabled
        - is_deleted
        - created_at
  parameters:
    cursor:
      name: cursor
      in: query
      description: Cursor value obtained from a previous request to the same endpoint. If not present, the first page of results is returned.
      required: false
      schema:
        type: string
        example: gfdeJjyBPOKjNzp9Ofwqs_ORmzlhShs0cYGMoWQADxNgH2WYv2hShEnbQxtnPL071nmpp4yoPG4VIA==
    sort:
      name: sort
      in: query
      description: Sort order. Field name, followed by `:asc` or `:desc`. Defaults to `created_at:desc` if that field exists, otherwise `id:desc`. Depending on the endpoint, sorting on some fields might not be supported.
      required: false
      schema:
        type: string
        example: name:asc
    limit:
      name: limit
      in: query
      description: Items per page.
      required: false
      schema:
        type: integer
        example: 20
    q:
      name: q
      in: query
      description: Search parameter
      required: false
      schema:
        type: string
        example: Barcelona
    is_deleted:
      name: is_deleted
      in: query
      description: Filter by deletion status
      required: false
      schema:
        type: string
        enum: ["true", "false", "any"]