Cobot External Resource API

openapi: 3.2.0
info:
  title: Cobot External 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: External Resource
  description: 'A space''s resources can be enabled for external booking, which means they can be booked

    by guests without a Cobot account or space membership. All resources enabled for external booking

    appear under external resources.

    '
paths:
  /external_resources:
    post:
      summary: Create
      description: 'Create an external resource for a resource. Attributes set on the external

        resource override the attributes of the related resource. Attributes left

        null on the external resource will fall back to the related resource.


        **Access**: The current user must be an admin of the space the resource belongs to.

        '
      operationId: create-external-resource
      security:
      - OAuth2:
        - write_external_resources
      tags:
      - External Resource
      responses:
        '201':
          description: The created resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-resource'
              examples:
                default:
                  value:
                    data:
                      id: a4a99a71ac8df98d29de357180d273d3
                      type: externalResources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        accountingCode: EXTR
                        costCenter:
                          name: External Bookings
                          number: MR1
                        revenueAccount:
                          name: External Bookings
                          number: '4000'
                        pricing:
                          currency: EUR
                          taxes:
                          - name: Tax
                            rate: '20.0'
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - name: Tax
                              rate: '20.0'
                              amount: '2.0'
                          priceCap:
                            maximumDuration:
                              hours: 12
                              minutes: 30
                          discounts:
                          - pricePerHour:
                              net: '5.0'
                              gross: '6.0'
                              currency: EUR
                              taxes:
                              - name: Tax
                                rate: '20.0'
                                amount: '1.0'
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '50.0'
                              gross: '60.0'
                              currency: EUR
                              taxes:
                              - name: Tax
                                rate: '20.0'
                                amount: '10.0'
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        description: Meeting Room
                        instructions: Ring the bell and wait for the door to be opened.
                        cancellationPeriod: 120
                        bookingCutoff: 1
                        effectiveBookingCutoff: 1
                        minBookingDuration: 60
                        maxBookingDuration: 480
                        capacity: 1
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        color: '#ff0000'
                        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
                        bookingsRequireApproval: true
                        payLater: false
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resource:
                          data:
                            id: 34e3ccee-4eb1-5b1d-b625-5bb34cefe28e
                            type: resources
                        resourceAvailability:
                          links:
                            related: https://api.cobot.me/external_resources/a4a99a71ac8df98d29de357180d273d3/availability
                        products:
                          data:
                          - id: 69efec34ba8df98d29de35cc80d27565
                            type: products
        '402':
          description: 'External resources are a paid add-on.

            The space does not have the required subscription.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - title: Payment required
                      detail: 'This API requires the space to have the external bookings subscription.

                        '
      requestBody:
        description: 'External resource data needed to create the external resource.

          At the very least a relationship to a resource is required.

          '
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-external-resource'
            examples:
              default:
                value:
                  data:
                    type: externalResources
                    attributes:
                      description: Meeting Room
                      pricing:
                        pricePerHour:
                          net: '10.0'
                        taxes:
                        - rate: '20.0'
                          name: Tax
                        discounts:
                        - pricePerHour:
                            net: '5'
                          minimumDuration:
                            hours: 2
                            minutes: 0
                        priceCaps:
                        - price:
                            net: '50'
                          maximumDuration:
                            hours: 8
                            minutes: 30
                      accountingCode: EXTR
                      costCenter:
                        name: External Bookings
                        number: Room 1
                      revenueAccount:
                        name: External Bookings
                        number: '4000'
                      maxBookingDuration: 480
                      minBookingDuration: 60
                      bookingTimesString: mo - tu 15:00 - 16:00
                      cancellationPeriod: 120
                      bookingsRequireApproval: true
                      payLater: false
                    relationships:
                      resource:
                        data:
                          id: 89da3cb66b5e6b39007690854kd66da4
                          type: resources
                      products:
                        data:
                        - id: 69efec34ba8df98d29de35cc80d27565
                          type: products
  /external_resources/{id}:
    get:
      summary: Single resource
      description: 'Show a single resource enabled for external booking.


        **Access**: Any user can access any space''s external resources.

        '
      operationId: get-external-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_external_resources
      tags:
      - External Resource
      responses:
        '200':
          description: A single resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-resource'
              examples:
                default:
                  value:
                    data:
                      id: a4a99a71ac8df98d29de357180d273d3
                      type: externalResources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        accountingCode: EXTR
                        costCenter:
                          name: External Bookings
                          number: MR1
                        revenueAccount:
                          name: External Bookings
                          number: '4000'
                        pricing:
                          currency: EUR
                          taxes:
                          - name: Tax
                            rate: '20.0'
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - name: Tax
                              rate: '20.0'
                              amount: '2.0'
                          priceCap:
                            maximumDuration:
                              hours: 12
                              minutes: 30
                          discounts:
                          - pricePerHour:
                              net: '5.0'
                              gross: '6.0'
                              currency: EUR
                              taxes:
                              - name: Tax
                                rate: '20.0'
                                amount: '1.0'
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '50.0'
                              gross: '60.0'
                              currency: EUR
                              taxes:
                              - name: Tax
                                rate: '20.0'
                                amount: '10.0'
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        description: Meeting Room
                        instructions: Ring the bell and wait for the door to be opened.
                        cancellationPeriod: 120
                        bookingCutoff: 1
                        effectiveBookingCutoff: 1
                        minBookingDuration: 60
                        maxBookingDuration: 480
                        capacity: 1
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        color: '#ff0000'
                        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
                        bookingsRequireApproval: true
                        payLater: false
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resource:
                          data:
                            id: 34e3ccee-4eb1-5b1d-b625-5bb34cefe28e
                            type: resources
                        resourceAvailability:
                          links:
                            related: https://api.cobot.me/external_resources/a4a99a71ac8df98d29de357180d273d3/availability
                        products:
                          data:
                          - id: 69efec34ba8df98d29de35cc80d27565
                            type: products
        '402':
          description: 'External resources are a paid add-on.

            The space does not have the required subscription.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - title: Payment required
                      detail: 'This API requires the space to have the external bookings subscription.

                        '
    patch:
      summary: Update resource
      description: 'Update a resource enabled for external booking.


        **Access**: The current user must be an admin of the space the resource belongs to.

        '
      operationId: patch-external-resource
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the external resource.
        schema:
          type: string
      security:
      - OAuth2:
        - write_external_resources
      tags:
      - External Resource
      requestBody:
        description: The external resource attributes to update.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/update-external-resource'
            examples:
              default:
                value:
                  data:
                    type: externalResources
                    id: 2c2a8092-3273-50da-ba45-23badf1cdc5d
                    attributes:
                      pricing:
                        taxes:
                        - rate: '20.0'
                          name: Tax
                        pricePerHour:
                          net: '10.0'
                      description: Meeting Room
                      cancellationPeriod: 120
                      minBookingDuration: 60
                      maxBookingDuration: 480
                      bookingTimesString: mo - tu 15:00 - 16:00
                      bookingsRequireApproval: true
                      payLater: false
      responses:
        '200':
          description: The updated external resource.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-resource'
              examples:
                default:
                  value:
                    data:
                      id: a4a99a71ac8df98d29de357180d273d3
                      type: externalResources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        accountingCode: EXTR
                        costCenter:
                          name: External Bookings
                          number: MR1
                        revenueAccount:
                          name: External Bookings
                          number: '4000'
                        pricing:
                          currency: EUR
                          taxes:
                          - name: Tax
                            rate: '20.0'
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - name: Tax
                              rate: '20.0'
                              amount: '2.0'
                          priceCap:
                            maximumDuration:
                              hours: 12
                              minutes: 30
                          discounts:
                          - pricePerHour:
                              net: '5.0'
                              gross: '6.0'
                              currency: EUR
                              taxes:
                              - name: Tax
                                rate: '20.0'
                                amount: '1.0'
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              net: '50.0'
                              gross: '60.0'
                              currency: EUR
                              taxes:
                              - name: Tax
                                rate: '20.0'
                                amount: '10.0'
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        description: Meeting Room
                        instructions: Ring the bell and wait for the door to be opened.
                        cancellationPeriod: 120
                        bookingCutoff: 1
                        effectiveBookingCutoff: 1
                        minBookingDuration: 60
                        maxBookingDuration: 480
                        capacity: 1
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        color: '#ff0000'
                        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
                        bookingsRequireApproval: true
                        payLater: false
                      relationships:
                        space:
                          data:
                            id: a927aa71ac8df98d29de357180d275a2
                            type: spaces
                        resource:
                          data:
                            id: 34e3ccee-4eb1-5b1d-b625-5bb34cefe28e
                            type: resources
                        resourceAvailability:
                          links:
                            related: https://api.cobot.me/external_resources/a4a99a71ac8df98d29de357180d273d3/availability
                        products:
                          data:
                          - id: 69efec34ba8df98d29de35cc80d27565
                            type: products
        '402':
          description: 'External resources are a paid add-on.

            The space does not have the required subscription.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - title: Payment required
                      detail: 'This API requires the space to have the external bookings subscription.

                        '
    delete:
      summary: Delete
      description: 'Delete an external resource. The original resource the external resource is connected to is not deleted.


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

        '
      operationId: delete-external-resource
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the resource.
        schema:
          type: string
      security:
      - OAuth2:
        - write_external_resources
      tags:
      - External Resource
      responses:
        '204':
          description: No content.
        '402':
          description: 'External resources are a paid add-on.

            The space does not have the required subscription.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - title: Payment required
                      detail: 'This API requires the space to have the external bookings subscription.

                        '
  /external_resources/{id}/availability:
    get:
      summary: Availability
      description: 'See the times an external resource is still available to book. Considers existing

        bookings, the resource''s booking times and calendar blockers.


        **Access**: Any user can access any space''s external resources.

        '
      operationId: get-external-resource-availbility
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the external resource.
        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
      security:
      - OAuth2:
        - read_external_resources
      tags:
      - External Resource
      responses:
        '200':
          description: Available booking times.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/resource-availability'
              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: externalResources
        '402':
          description: 'External resources are a paid add-on.

            The space does not have the required subscription.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - title: Payment required
                      detail: 'This API requires the space to have the external bookings subscription.

                        '
  /spaces/{spaceId}/external_resources:
    get:
      summary: List for space
      description: 'List the resources enabled for external booking for a space.


        These resources can be booked and paid for by non-members of a space.


        **Access**: Any user can access any space''s external resources.

        '
      operationId: get-external-resources
      parameters:
      - name: spaceId
        in: path
        required: true
        description: The id of the space to get the resources for.
        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_external_resources
      tags:
      - External Resource
      responses:
        '200':
          description: The resources enabled for external booking of a space.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-resources'
              examples:
                default:
                  value:
                    data:
                    - id: a4a99a71ac8df98d29de357180d273d3
                      type: externalResources
                      attributes:
                        name: Meeting Room
                        resourceType: room
                        accountingCode: EXTR
                        costCenter:
                          name: External Bookings
                          number: MR1
                        revenueAccount:
                          name: External Bookings
                          number: '4000'
                        pricing:
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                          pricePerHour:
                            net: '10.0'
                            gross: '12.0'
                            currency: EUR
                            taxes:
                            - name: Tax
                              rate: '20.0'
                              amount: '1.0'
                          priceCap:
                            maximumDuration:
                              hours: 12
                              minutes: 30
                          discounts:
                          - pricePerHour:
                              $ref: ../examples/price.yml
                            minimumDuration:
                              hours: 2
                              minutes: 0
                          priceCaps:
                          - price:
                              $ref: ../examples/price.yml
                            maximumDuration:
                              hours: 8
                              minutes: 30
                        cancellationPeriod: 120
                        bookingCutoff: 1
                        effectiveBookingCutoff: 1
                        description: Large room, fits 12.
                        instructions: Ring the bell and wait for the door to be opened.
                        minBookingDuration: 10
                        maxBookingDuration: 20
                        capacity: 1
                        area:
                        - unit: sqm
                          number: 40
                        - unit: sqft
                          number: 431
                        areaPreferredUnit: sqm
                        color: '#ff0000'
                        photo:
                          icon:
                            url: https://cdn.com/resource/photo/a4a99a71ac8df98d29de357180

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