Cobot Booking API

openapi: 3.2.0
info:
  title: Cobot Booking 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: Booking
  description: A booking of a resource in the booking calendar.
paths:
  /bookings:
    post:
      summary: Book as admin
      description: 'Create booking as an admin. Optionally a booking can be assigned to a membership.


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

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

        space in the network.

        '
      operationId: create-admin-booking
      security:
      - OAuth2:
        - write_bookings
      tags:
      - Booking
      responses:
        '201':
          description: New booking
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: bookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        units: 1
                        title: team meeting
                        url: https://example.com/team-meeting
                        comments: there is going to be coffe and cake
                        attendeesMessage: Please bring your laptop
                        attendees:
                        - email: attendee@example.com
                        price:
                          net: '10.0'
                          gross: '12.0'
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                        canUpdate: true
                        cancellationPeriod: 0
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: 89da3cb66b5e6b39007690854kd66da4
                            type: memberships
                        externalBooking:
                          data: null
        '202':
          description: 'New recurring booking. Returns 202 since the bookings are created

            asynchronously (except the first one).


            The bookings can be fetched via

            the _recurringBookings_ relationship, which also lets you track

            if all bookings have been written.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: bookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        units: 1
                        title: team meeting
                        url: https://example.com/team-meeting
                        comments: there is going to be coffe and cake
                        attendeesMessage: Please bring your laptop
                        attendees:
                        - email: attendee@example.com
                        price:
                          net: '10.0'
                          gross: '12.0'
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                        canUpdate: true
                        cancellationPeriod: 0
                        recurrence:
                          rule:
                            frequency: weekly
                            interval: 1
                            from: '2018-01-01'
                            until: '2018-01-22'
                            count: null
                            weekdays: null
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        recurringBookings:
                          links:
                            related: /recurring_bookings/a3281b61ac8df98d29de357180d212e4
                        followingRecurringBookings:
                          links:
                            related: /bookings/a3281b61ac8df98d29de357180d212e4/following
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: 89da3cb66b5e6b39007690854kd66da4
                            type: memberships
                        externalBooking:
                          data: null
        '400':
          description: 'The booking''s resource is not bookable.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - detail: Resource is not bookable.
      requestBody:
        description: Booking to be created
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-booking'
            examples:
              default:
                value:
                  data:
                    type: bookings
                    attributes:
                      from: '2018-01-01T12:00:00Z'
                      to: '2018-01-01T14:00:00Z'
                      units: 1
                      title: team meeting
                      url: https://example.com/team-meeting
                      comments: there is going to be coffe and cake
                      attendeesMessage: Please bring your laptop
                      attendees:
                      - email: attendee@example.com
                      customPrice:
                        net: '12.00'
                    relationships:
                      resource:
                        data:
                          id: 99da6cb66b5e6b39007690854fd66df9
                          type: resources
                      membership:
                        data:
                          id: 89da3cb66b5e6b39007690854kd66da4
                          type: memberships
              recurring:
                value:
                  data:
                    type: bookings
                    attributes:
                      from: '2018-01-01T12:00:00Z'
                      to: '2018-01-01T14:00:00Z'
                      units: 1
                      recurrence:
                        rule:
                          frequency: weekly
                          interval: 1
                          until: '2018-01-22'
                          weekdays:
                          - 1
                          - 3
                    relationships:
                      resource:
                        data:
                          id: 99da6cb66b5e6b39007690854fd66df9
                          type: resources
                      membership:
                        data:
                          id: 89da3cb66b5e6b39007690854kd66da4
                          type: memberships
  /recurring_bookings/{recurringId}:
    get:
      summary: List recurring
      description: 'List all the recurring bookings belonging to a booking with recurrence.


        The data returned by this endpoint is only eventually consistent.


        **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-recurring-bookings
      parameters:
      - name: recurringId
        in: path
        required: true
        description: The id of the recurrence.
        schema:
          type: string
      security:
      - OAuth2:
        - read_bookings
      tags:
      - Booking
      responses:
        '200':
          description: All bookings belonging to the same recurrence.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/recurring-bookings'
              examples:
                default:
                  value:
                    data:
                    - id: b8f21a71ac8df98d29de357180d27358
                      type: bookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        title: meeting
                        url: https://example.com/meeting
                        comments: nil
                        attendees: []
                        price:
                          $ref: ../examples/price.yml
                        canUpdate: true
                        units: 1
                        cancellationPeriod: 0
                        recurrence:
                          rule:
                            frequency: weekly
                            interval: 1
                            from: '2018-01-01'
                            until: '2018-01-22'
                            weekdays: null
                            count: null
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: f11h2a71ac8df98d29de357180d273a3
                            type: memberships
                        recurringBookings:
                          links:
                            related: /recurring_bookings/a3281b61ac8df98d29de357180d212e4
                        followingRecurringBookings:
                          links:
                            related: /bookings/b8f21a71ac8df98d29de357180d27358/following
                        externalBooking:
                          data: null
                    meta:
                      consistent: true
                      totalPages: 1
                      currentPage: 1
  /recurring_bookings/{bookingId}/following:
    delete:
      summary: Delete following
      description: 'Delete a recurring booking and all the following instances.


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

        '
      operationId: delete-following-recurring-bookings
      parameters:
      - name: bookingId
        in: path
        required: true
        description: The id of the booking to delete.
        schema:
          type: string
      security:
      - OAuth2:
        - write_bookings
      tags:
      - Booking
      responses:
        '202':
          description: The deleted booking.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: bookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        title: meeting
                        url: https://example.com/meeting
                        comments: nil
                        attendees: []
                        price:
                          net: '10.0'
                          gross: '12.0'
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                        canUpdate: true
                        cancellationPeriod: 0
                        units: 1
                        recurrence:
                          rule:
                            frequency: weekly
                            interval: 1
                            from: '2018-01-01'
                            until: '2018-01-22'
                            count: null
                            weekdays: null
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: f11h2a71ac8df98d29de357180d273a3
                            type: memberships
                        recurringBookings:
                          links:
                            related: /recurring_bookings/a3281b61ac8df98d29de357180d212e4
                        followingRecurringBookings:
                          links:
                            related: /bookings/b8f21a71ac8df98d29de357180d27358/following
                        externalBooking:
                          data: null
  /bookings_preview:
    post:
      summary: Bookings preview
      description: 'Return all booking previews for given resources for a membership in the given time range.


        **Access**: The current user must be the owner of the membership the booking belongs to or an admin of the space or network.

        '
      operationId: post-bookings-preview
      requestBody:
        description: The time range and resource ids list.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-bookings-preview'
            examples:
              default:
                value:
                  data:
                    type: bookingPreviews
                    attributes:
                      from: '2018-01-01T12:00:00Z'
                      to: '2018-01-01T14:00:00Z'
                    relationships:
                      booking:
                        data:
                          id: 42ac6cb66b5ebb30007290854fd46ae0
                          type: bookings
                      resources:
                        data:
                        - id: 99da6cb66b5e6b39007690854fd66df9
                          type: resources
                      membership:
                        data:
                          id: 89da3cb66b5e6b39007690854kd66da4
                          type: memberships
              recurring:
                value:
                  data:
                    type: bookingPreviews
                    attributes:
                      from: '2018-01-01T12:00:00Z'
                      to: '2018-01-01T14:00:00Z'
                      recurrence:
                        rule:
                          frequency: daily
                          from: '2018-01-01'
                          until: '2018-01-02'
                    relationships:
                      resources:
                        data:
                        - id: 99da6cb66b5e6b39007690854fd66df9
                          type: resources
                      membership:
                        data:
                          id: 89da3cb66b5e6b39007690854kd66da4
                          type: memberships
      security:
      - OAuth2:
        - read_resources
        - read_memberships
      tags:
      - Booking
      responses:
        '200':
          description: Booking previews for given resources for a membership in the given time range.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/booking-previews'
              examples:
                default:
                  value:
                    data:
                    - id: b8f21a71ac8df98d29de357180d27358
                      type: bookingPreviews
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        appliedDiscounts:
                        - pricePerHour:
                            net: '6.0'
                            gross: '6.6'
                            currency: EUR
                            taxes:
                            - rate: '10.0'
                              amount: '0.6'
                              name: VAT
                          minimumDuration:
                            hours: 1
                            minutes: 0
                        appliedFixedRates:
                        - maximumDuration:
                            hours: 2
                            minutes: 0
                          price: '10.0'
                          count: 2
                        appliedPriceCap:
                          maximumDuration:
                            hours: 2
                            minutes: 0
                        attendees: []
                        title: meeting
                        comments: null
                        price:
                          $ref: ../examples/price.yml
                        estimatedPayablePrice:
                          $ref: ../examples/price.yml
                        canUpdate: true
                        cancellationPeriod: 0
                        bookingExtras: []
                        bookingCredits:
                          estimatedMinutesUsed: 30
                          estimatedAmountUsed:
                            $ref: ../examples/price.yml
                        bookingPasses:
                          estimatedMinutesUsed: 60
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: b5a99a71ac8df98d2gn8380d273d3
                            type: memberships
                        externalBooking:
                          data: null
                recurring:
                  value:
                    data:
                    - id: b8f21a71ac8df98d29de357180d27358
                      type: bookingPreviews
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        appliedDiscounts:
                        - pricePerHour:
                            net: '6.0'
                            gross: '6.6'
                            currency: EUR
                            taxes:
                            - rate: '10.0'
                              amount: '0.6'
                              name: VAT
                          minimumDuration:
                            hours: 1
                            minutes: 0
                        appliedFixedRates:
                        - maximumDuration:
                            hours: 2
                            minutes: 0
                          price: '10.0'
                          count: 2
                        appliedPriceCap:
                          maximumDuration:
                            hours: 2
                            minutes: 0
                        attendees: []
                        title: meeting
                        comments: null
                        price:
                          $ref: ../examples/price.yml
                        estimatedPayablePrice:
                          $ref: ../examples/price.yml
                        canUpdate: true
                        cancellationPeriod: 0
                        bookingExtras: []
                        errors: {}
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: b5a99a71ac8df98d2gn8380d273d3
                            type: memberships
                        externalBooking:
                          data: null
                    - id: cy75b4b9b5y34e656d76phobaf79my9i
                      type: bookingPreviews
                      attributes:
                        from: '2018-01-02T12:00:00Z'
                        to: '2018-01-02T14:00:00Z'
                        appliedDiscounts:
                        - pricePerHour:
                            net: '6.0'
                            gross: '6.6'
                            currency: EUR
                            taxes:
                            - rate: '10.0'
                              amount: '0.6'
                              name: VAT
                          minimumDuration:
                            hours: 1
                            minutes: 0
                        appliedFixedRates:
                        - maximumDuration:
                            hours: 2
                            minutes: 0
                          price: '10.0'
                          count: 2
                        appliedPriceCap:
                          maximumDuration:
                            hours: 2
                            minutes: 0
                        attendees: []
                        title: meeting
                        comments: null
                        price:
                          $ref: ../examples/price.yml
                        estimatedPayablePrice:
                          $ref: ../examples/price.yml
                        canUpdate: true
                        cancellationPeriod: 0
                        bookingExtras: []
                        errors: {}
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        membership:
                          data:
                            id: b5a99a71ac8df98d2gn8380d273d3
                            type: memberships
                        externalBooking:
                          data: null
                    meta:
                      totalBookings: 2
                      totalPrice: '120.00'
  /bookings/{id}:
    delete:
      summary: Delete booking
      description: '**Access**: The current user must either be an admin or a member of a space or the space''s network. A member can only delete their own bookings and additionally only those that are not in the past.

        '
      operationId: delete-space-booking
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking to be deleted.
        schema:
          type: string
      security:
      - OAuth2:
        - write_bookings
      tags:
      - Booking
      responses:
        '204':
          description: Booking deleted.
        '409':
          description: Booking has been made by an event and can't be deleted through this endpoint.
    get:
      summary: Single booking
      description: '**Access**: The current user must be an admin or member of the space

        the booking belongs to. If the

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

        space in the network.

        '
      operationId: get-booking
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking.
        schema:
          type: string
      security:
      - OAuth2:
        - read_bookings
      tags:
      - Booking
      responses:
        '200':
          description: Details of a booking.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: bookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        units: 1
                        title: meeting
                        url: https://example.com/meeting
                        name: joe
                        comments: nil
                        attendeesMessage: null
                        attendees:
                        - email: attendee@example.com
                        hasCustomPrice: false
                        price:
                          net: '10.0'
                          gross: '12.0'
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                        canUpdate: true
                        cancellationPeriod: 0
                        bookingCredits:
                          estimatedMinutesUsed: 30
                        bookingPasses:
                          estimatedMinutesUsed: 60
                        estimatedPayablePrice:
                          net: '10.0'
                          gross: '12.0'
                          currency: EUR
                          taxes:
                          - rate: '20.0'
                            name: Tax
                        bookingExtras:
                        - name: Cup of coffee
                          accountingCode: coffee1
                          description: Hot
                          id: extra-uuid-1234
                          productId: a1b2c3d4e5f6
                          pricing:
                            amount:
                              net: '1.0'
                              gross: '1.1'
                              currency: EUR
                              taxes:
                              - rate: '10.0'
                                amount: '0.1'
                                name: VAT
                            totalAmount:
                              net: '2.0'
                              gross: '2.2'
                              currency: EUR
                              taxes:
                              - rate: '10.0'
                                amount: '0.2'
                                name: VAT
                            quantity: '2.0'
                            unit: item
                      relationships:
                        space:
                          data:
                            id: f9a99a71ac8df98d29de357180d273d3
                            type: spaces
                        resource:
                          data:
                            id: a4a99a71ac8df98d29de357180d273d3
                            type: resources
                        externalBooking:
                          data: null
    patch:
      summary: Update booking
      description: '**Access**: The current user must either be an admin or a member of a space or the space''s network. A member can only update their own bookings and additionally only those that are not in the past.

        '
      operationId: update-space-booking
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking to be updated.
        schema:
          type: string
      security:
      - OAuth2:
        - write_bookings
      tags:
      - Booking
      requestBody:
        description: Booking to be updated
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/update-booking'
            examples:
              default:
                value:
                  data:
                    i

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