Cobot Resource API

openapi: 3.2.0
info:
  title: Cobot Resource API
  termsOfService: https://www.cobot.me/terms
  x-logo:
    url: /api2_logo.webp
    backgroundColor: '#FFFFFF'
    altText: Cobot logo
  description: "This is the 2.0 version of the Cobot API. You can find version 1.0\nas well as various tutorials under [/api-docs](/api-docs).\n\n## JSON API\n\nThis API follows the [JSON API](http://jsonapi.org) standard. This means:\n\n* requests and responses are sent in JSON\n* all requests MUST send a `Accept: application/vnd.api+json` header\n* non-GET requests MUST send a `Content-Type: application/vnd.api+json` header\n* all responses send a `Content-Type: application/vnd.api+json` header\n* all JSON formats are standardized (requests, responses, errors)\n\n## Cross-Origin Resource Sharing (CORS)\n\nAll endpoints send [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)\nheaders so that the API can be used from within browsers.\n\n## Rate Limiting\n\nIn general, the rate limit for an endpoint is 60 requests per minute per user.\nIf applicable, alternative limits are given in the documentation for\nparticular endpoints.\n\nIf you've exceeded the limit, Cobot will return a 429 status code and a JSON\nerror message. The response will also contain a *Retry-After* header, this\ndenotes the number of seconds to wait before your client may retry.\n\n## Times and Dates\n\nTimes and Dates must be in ISO 8601 formats. e.g. date: `2021-01-07`, datetime: `2021-01-07T16:25:51Z`,  time: `16:25:51`.\nMillisecond are ommited, so `16:25:51.811` will become `16:25:51`.\nTime zone offsets must be provided by the client, e.g. `16:25:51+02:00` or '16:25:51Z' for UTC.\n\nTimes are always returned in UTC.\n## Sparse Fieldsets\n\nThis API supports [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets),\nso clients can request which attributes they are interested in.\n\nExample:\n```\nGET https://api.cobot.me/user?fields[users]=email\n```\nThis will only return the user's email.\n\n## Query params\n\nWhen passing query params, arrays of data are expected to be sent as a string of comma separated values.\n\n## Pagination\n\nAll collections are paginated. Pagination follows [JSON-API standards](https://jsonapi.org/format/#fetching-pagination).\n\nExample:\n```json\n{\n  \"meta\": {\n    \"totalPages\": 2,\n    \"currentPage\": 1\n  },\n  \"data\": [{\n    \"id\": \"1\",\n    \"type\": \"users\",\n  }],\n  \"links\": {\n    \"self\": \"/users?page[size]=100&page[number]=1\",\n    \"first\": \"/users?page[size]=100&page[number]=1\",\n    \"prev\": null,\n    \"next\": \"/users?page[size]=100&page[number]=2\",\n    \"last\": \"/users?page[size]=100&page[number]=1\"\n  }\n}\n```\n\nDefault page size is 72 and can be changed by passing a `page[size]` parameter. Maximum page size is 200.\n\n## Errors\n\nWhen a client sends invalid data in a request, Cobot returns a\n422 status code and a JSON-API error response.\n\nExample:\n```json\n{\n  \"errors\": [\n    {\n      \"source\": {\n        \"pointer\": \"/data/attributes/name\"\n      },\n      \"detail\": \"can't be blank\"\n    },\n    {\n      \"source\": {\n        \"pointer\": \"/data/attributes/password\"\n      },\n      \"detail\": \"is too short\"\n    }\n  ]\n}\n```\n"
  version: '2.0'
  contact:
    name: Cobot Support
    url: https://dev.cobot.me/
    email: support@cobot.me
servers:
- url: https://api.cobot.me
security:
- OAuth2: []
tags:
- name: Resource
  description: A resource can be booked on an hourly basis using the booking calendar. Examples are conference rooms, presentation equipment, bikes etc.
paths:
  /networks/{networkId}/resource_availabilities:
    get:
      summary: List network resource availabilities
      description: 'List the availability of multiple resources across all spaces in a network for a given time range. Considers existing bookings, each resource''s booking times, cutoff, and calendar blockers.


        Only resources that belong to spaces within the specified network will be included in the results. Resource IDs from outside the network will be filtered out.


        **Access**: The current user must be an admin or member of any space in the network.

        '
      operationId: get-network-resource-availabilities
      parameters:
      - name: networkId
        in: path
        required: true
        description: The id of the network.
        schema:
          type: string
      - name: filter[from]
        in: query
        required: true
        description: The time from when on to return the availability.
        schema:
          type: string
          format: date-time
      - name: filter[to]
        in: query
        required: true
        description: The time until when to return the availability.
        schema:
          type: string
          format: date-time
      - name: filter[resourceIds]
        in: query
        required: false
        style: form
        explode: false
        description: Comma-separated list of resource ids to return availabilities for. Only resources belonging to spaces in this network will be included.
        schema:
          type: array
          items:
            type: string
      security:
      - OAuth2:
        - read_resources
      tags:
      - Resource
      responses:
        '200':
          description: Availabilities for the requested resources within the network.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/resource-availabilities'
              examples:
                default:
                  value:
                    data:
                    - id: a4a99a71ac8df98d29de357180d273d3
                      type: resourceAvailabilities
                      attributes:
                        availableTimes:
                        - from: '2018-01-01T10:00:00Z'
                          to: '2018-01-01T12:00:00Z'
                        - from: '2018-01-01T14:30:00Z'
                          to: '2018-01-01T19:00:00Z'
                      relationships:
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                    - id: b7b99a71ac8df98d29de357180d273d4
                      type: resourceAvailabilities
                      attributes:
                        availableTimes:
                        - from: '2018-01-01T09:00:00Z'
                          to: '2018-01-01T11:00:00Z'
                      relationships:
                        resource:
                          data:
                            id: b7b99a71ac8df98d29de357180d273d4
                            type: resources
  /networks/{networkId}/resources:
    get:
      summary: List for network
      description: 'Get a list of resources for all spaces in a network.


        **Access**: The current user must be an admin or member of any

        space in the network.

        '
      operationId: get-network-resources
      parameters:
      - name: networkId
        in: path
        description: Id of the network.
        required: true
        schema:
          type: string
      - name: filter[usage]
        in: query
        description: 'Filter resources by their usage. Defaults to `bookable` for backward compatibility.

          '
        required: false
        schema:
          type: string
          enum:
          - bookable
          - allocatable
          - all
          default: bookable
      - name: filter[spaceIds]
        in: query
        description: 'Comma-separated list of space IDs to filter resources by.

          If omitted, returns resources for all spaces in the network.

          '
        required: false
        schema:
          type: string
          example: space1,space2,space3
      security:
      - OAuth2:
        - read_resources
      tags:
      - Resource
      responses:
        '200':
          description: 'Returns the resources of all spaces in the network (or filtered spaces if specified).

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/resources'
              examples:
                default:
                  value:
                    data:
                    - id: a4a99a71ac8df98d29de357180d273d3
                      type: resources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        usage: bookable
                        pricing:
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - rate: '20.0'
                              name: Tax
                          priceCap:
                            maximumDuration:
                              hours: 8
                              minutes: 0
                          discounts:
                          - pricePerHour:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        accountingCode: ROOM
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        costCenter:
                          name: Room Bookings
                          number: ROOM3
                        revenueAccount:
                          name: Room Bookings
                          number: '4000'
                        description: Large room, fits 12.
                        hidden: false
                        units: 2
                        capacity: 12
                        minBookingDuration: 10
                        maxBookingDuration: 20
                        color: '#ff0000'
                        bookingCutoff: 1
                        cancellationPeriod: 0
                        onlyAdminsCanBook: false
                        canBook: true
                        photo:
                          icon:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/icon_photo.png
                            width: 120
                            height: 120
                          default:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/default_photo.png
                            width: 800
                            height: 600
                        bookingTimesString: mo - tu 15:00 - 16:00
                        bookingTimes:
                        - from: '15:00'
                          to: '16:00'
                          weekdays:
                          - 1
                          - 2
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resourceAvailability:
                          links:
                            related: https://api.cobot.me/resources/a4a99a71ac8df98d29de357180d273d3/availability
                        categories:
                          data:
                          - id: f227aa71ac8df98d29de357180d275a2
                            type: resourceCategories
                        media:
                          data:
                          - id: b6288a71ac8df98d29de357180d21c99
                            type: resourcePhotos
                        products:
                          data:
                          - id: 69efec34ba8df98d29de35cc80d27565
                            type: products
  /networks/{networkId}/resources/available:
    get:
      summary: Available resources for network
      description: 'List the bookable resources that are available to book at a given time across all spaces in a network.

        This means there are fewer existing bookings than the resources'' units.

        For members, the resources'' `booking_times`, cutoff, min/max duration and calendar blockers are also taken into account.


        Only resources with `usage: bookable` are returned. Allocatable resources are not included.


        **Access**: The current user must be an admin or member of any

        space in the network.

        '
      operationId: get-available-network-resources
      parameters:
      - name: networkId
        in: path
        required: true
        description: Id of the network.
        schema:
          type: string
      - name: filter[from]
        in: query
        required: true
        description: The start of the timespan to check for availability.
        schema:
          type: string
          format: date-time
      - name: filter[to]
        in: query
        required: true
        description: The end of the timespan to check for availability.
        schema:
          type: string
          format: date-time
      - name: filter[spaceIds]
        in: query
        required: false
        description: 'Comma-separated list of space IDs to filter resources by.

          If omitted, returns resources for all spaces in the network.

          '
        schema:
          type: string
          example: space1,space2,space3
      - name: filter[ignoreBookingId]
        in: query
        required: false
        description: Id of a booking to not consider when determining availability. Useful for determining availbility before moving a booking to a different time.
        schema:
          type: string
      - name: filter[ignoreBookingTimes]
        in: query
        required: false
        description: If set to true, returns resources as available even when the requested time is outside of the resource's booking times setting or blocked by calendar blockers. Option available only for admins of a space.
        schema:
          type: string
          enum:
          - true
          - false
      - name: filter[resourceIds]
        in: query
        required: false
        style: form
        explode: false
        description: Limit returned resources to the given resource ids (comma separated).
        schema:
          type: array
          items:
            type: string
      security:
      - OAuth2:
        - read_resources
      tags:
      - Resource
      responses:
        '200':
          description: 'The resources of all spaces in the network that are available to book at the given time.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/resources'
              examples:
                default:
                  value:
                    data:
                    - id: a4a99a71ac8df98d29de357180d273d3
                      type: resources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        usage: bookable
                        pricing:
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - rate: '20.0'
                              name: Tax
                          priceCap:
                            maximumDuration:
                              hours: 8
                              minutes: 0
                          discounts:
                          - pricePerHour:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        accountingCode: ROOM
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        costCenter:
                          name: Room Bookings
                          number: ROOM3
                        revenueAccount:
                          name: Room Bookings
                          number: '4000'
                        description: Large room, fits 12.
                        hidden: false
                        units: 2
                        capacity: 12
                        minBookingDuration: 10
                        maxBookingDuration: 20
                        color: '#ff0000'
                        bookingCutoff: 1
                        cancellationPeriod: 0
                        onlyAdminsCanBook: false
                        canBook: true
                        photo:
                          icon:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/icon_photo.png
                            width: 120
                            height: 120
                          default:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/default_photo.png
                            width: 800
                            height: 600
                        bookingTimesString: mo - tu 15:00 - 16:00
                        bookingTimes:
                        - from: '15:00'
                          to: '16:00'
                          weekdays:
                          - 1
                          - 2
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resourceAvailability:
                          links:
                            related: https://api.cobot.me/resources/a4a99a71ac8df98d29de357180d273d3/availability
                        categories:
                          data:
                          - id: f227aa71ac8df98d29de357180d275a2
                            type: resourceCategories
                        media:
                          data:
                          - id: b6288a71ac8df98d29de357180d21c99
                            type: resourcePhotos
                        products:
                          data:
                          - id: 69efec34ba8df98d29de35cc80d27565
                            type: products
  /resources:
    post:
      summary: Create resource
      description: 'Create a new resource in a space.


        **Access**: The current user must be an admin of the space

        the resource if created in.

        '
      operationId: post-resources
      security:
      - OAuth2:
        - write_resources
      tags:
      - Resource
      requestBody:
        description: Data to create a resource.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-resource'
            examples:
              default:
                value:
                  data:
                    type: resources
                    attributes:
                      name: Meeting Room
                      resourceType: room
                      pricing:
                        currency: EUR
                        taxes:
                        - rate: '20.0'
                          name: Tax
                        pricePerHour:
                          net: '10.0'
                        discounts:
                        - minimumDuration:
                            hours: 2
                            minutes: 30
                          pricePerHour:
                            net: '11.25'
                        priceCaps:
                        - maximumDuration:
                            hours: 4
                            minutes: 0
                          price:
                            net: '30.00'
                      description: Large room, fits 12.
                      units: 2
                      capacity: 12
                      bookingCutoff: 1
                      cancellationPeriod: 3
                      minBookingDuration: 30
                      maxBookingDuration: 480
                      color: '#ff0000'
                      photo:
                        data: data:image/png;base64,cGhvdG8=
                      bookingTimesString: mo - tu 15:00 - 16:00
                      costCenter:
                        name: Bookings
                        number: Room 1
                      revenueAccount:
                        name: Bookings
                        number: '4000'
                    relationships:
                      space:
                        data:
                          type: spaces
                          id: c4d25d6e-9409-5055-ba83-b75b9c253e75
      responses:
        '201':
          description: Details of the new resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/resource'
              examples:
                default:
                  value:
                    data:
                      id: a4a99a71ac8df98d29de357180d273d3
                      type: resources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        usage: bookable
                        pricing:
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - rate: '20.0'
                              name: Tax
                          priceCap:
                            maximumDuration:
                              hours: 8
                              minutes: 0
                          discounts:
                          - pricePerHour:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        accountingCode: ROOM
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        costCenter:
                          name: Room Bookings
                          number: ROOM3
                        revenueAccount:
                          name: Room Bookings
                          number: '4000'
                        description: Large room, fits 12.
                        hidden: false
                        units: 2
                        capacity: 12
                        minBookingDuration: 10
                        maxBookingDuration: 20
                        color: '#ff0000'
                        bookingCutoff: 1
                        cancellationPeriod: 0
                        onlyAdminsCanBook: false
                        canBook: true
                        photo:
                          icon:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/icon_photo.png
                            width: 120
                            height: 120
                          default:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/default_photo.png
                            width: 800
                            height: 600
                        bookingTimesString: mo - tu 15:00 - 16:00
                        bookingTimes:
                        - from: '15:00'
                          to: '16:00'
                          weekdays:
                          - 1
                          - 2
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resourceAvailability:
                          links:
                            related: https://api.cobot.me/resources/a4a99a71ac8df98d29de357180d273d3/availability
                        categories:
                          data:
                          - id: f227aa71ac8df98d29de357180d275a2
                            type: resourceCategories
                        media:
                          data:
                          - id: b6288a71ac8df98d29de357180d21c99
                            type: resourcePhotos
                        products:
                          data:
                          - id: 69efec34ba8df98d29de35cc80d27565
                            type: products
  /resources/{id}:
    get:
      summary: Get resource
      description: 'See details of the resource.


        **Access**: The current user must be an admin or member of the space. If the

        space is part of a network, the user must be an admin or member of any

        space in the network.

        '
      operationId: get-resource
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the resource.
        schema:
          type: string
      - name: include
        in: query
        description: 'List of related resources to include in response.

          `media` are the additional photos of a resource (the primary photo is

          in the `photo` attribute).

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - media
      security:
      - OAuth2:
        - read_resources
      tags:
      - Resource
      responses:
        '200':
          description: Details of the resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/resource'
              examples:
                default:
                  value:
                    data:
                      id: a4a99a71ac8df98d29de357180d273d3
                      type: resources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        usage: bookable
                        pricing:
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - rate: '20.0'
                              name: Tax
                          priceCap:
                            maximumDuration:
                              hours: 8
                              minutes: 0
                          discounts:
                          - pricePerHour:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '10.0'
                              gross: '12.0'
                              currency: EUR
                              taxes:
                              - rate: '20.0'
                                name: Tax
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        accountingCode: ROOM
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        costCenter:
                          name: Room Bookings
                          number: ROOM3
                        revenueAccount:
                          name: Room Bookings
                          number: '4000'
                        description: Large room, fits 12.
                        hidden: false
                        units: 2
                        capacity: 12
                        minBookingDuration: 10
                        maxBookingDuration: 20
                        color: '#ff0000'
                        bookingCutoff: 1
                        cancellationPeriod: 0
                        onlyAdminsCanBook: false
                        canBook: true
                        photo:
                          icon:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/icon_photo.png
                            width: 120
                            height: 120
                          default:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180d273d3/default_photo.png
                            width: 800
                            height: 600
                        bookingTimesString: mo - tu 15:00 - 16:00
                        bookingTimes:
                        - from: '15:00'
                          to: '16:00'
                          weekdays:
                          - 1
                          - 2
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resourceAvailability:
                          links:
                            relat

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