Cobot External Booking API

openapi: 3.2.0
info:
  title: Cobot External 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: External Booking
  description: 'After a resource has been enabled for external booking (see _External Resource_) it can be

    booked by visitors (non-members) using external booking endpoints.

    Making an external booking also results in a Booking to be created.

    '
paths:
  /external_bookings:
    post:
      summary: Create
      description: 'Create an external booking.


        **Access**: Any user can create external bookings.

        '
      operationId: create-external-booking
      security:
      - OAuth2:
        - write_external_bookings
      tags:
      - External Booking
      responses:
        '201':
          description: The created booking.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: externalBookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        title: Company Retreat
                        price:
                          net: '10.0'
                          gross: '11.0'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.0'
                            name: VAT
                        totalPrice:
                          net: '11.0'
                          gross: '12.1'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.1'
                            name: VAT
                        numberOfVisitors: 1
                        acceptedTerms: true
                        name: Earl McBride
                        company: ACME Inc.
                        billingAddress: 1422 Nuede Extension\nSpringfield, IL, 12345
                        structuredBillingAddress:
                          name: Earl McBride
                          company: ACME Inc.
                          fullAddress: 1422 Nuede Extension\nSpringfield, IL, 12345
                          street: 1422 Nuede Extension
                          postCode: '12345'
                          city: Springfield
                          state: IL
                          countryCode: US
                        taxId: 123456789A
                        phone: (959) 645-9532
                        email: fe@haos.eg
                        comments: we need catering
                        adminComments: make sure to air the room before
                        status: approved
                        accountingCode: EB1
                        canUpdate: true
                        discount:
                          code: SUMMER2024
                          name: Summer Sale
                          value: '10.0'
                          unit: percentage
                          amounts:
                          - net: '1.1'
                            gross: '1.21'
                            currency: EUR
                            taxes:
                            - rate: '10.0'
                              amount: '0.11'
                              name: VAT
                        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:
                        paymentMethod:
                          data: null
                        resource:
                          data:
                            id: 89da3cb66b5e6b39007690854kd66da4
                            type: externalResources
                        space:
                          data:
                            id: 99a12ca68b5e6bc9007890854kd368f2
                            type: spaces
                        invoices:
                          data:
                          - id: a07fed27-b35b-5c67-8367-3e52c397c528
                            type: invoices
                        contact:
                          data:
                            id: u2374d68h2j067d708qhj6whgn372872
                            type: contacts
        '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.
        '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.

                        '
        '422':
          description: 'When sending a payment and capturing the payment fails, an error is returned.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - detail: Payment could not be captured.
      requestBody:
        description: Booking data needed to make the booking.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-external-booking'
            examples:
              default:
                value:
                  data:
                    type: externalBookings
                    attributes:
                      from: '2018-01-01T12:00:00Z'
                      to: '2018-01-01T14:00:00Z'
                      title: Company Retreat
                      numberOfVisitors: 1
                      acceptedTerms: true
                      name: Earl McBride
                      company: ACME Inc.
                      billingAddress:
                        name: Earl McBride
                        company: ACME Inc.
                        street: 123 Main St
                        postCode: '12345'
                        city: Springfield
                        state: IL
                        countryCode: US
                      taxId: 123456789A
                      phone: (959) 645-9532
                      email: fe@haos.eg
                      comments: we need catering
                      adminComments: make sure to air the room before
                      bookingExtras:
                      - productId: 5d2bd10cdab1647e6e49dafa319ad365
                        quantity: '2.0'
                    relationships:
                      resource:
                        data:
                          id: 89da3cb66b5e6b39007690854kd66da4
                          type: externalResources
                      discount:
                        data:
                          id: e6a53fb4a996cfa147e174e265edc5e0
                          type: discountCodes
  /external_bookings/{id}:
    get:
      summary: Single booking
      description: 'Show an external booking.


        **Access**: Any user can see external bookings.

        '
      operationId: show-external-booking
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking.
        schema:
          type: string
      - name: include
        in: query
        required: false
        description: 'List of related resources to include in response as comma separated string.


          Including `invoices` requires the `read_invoices` scope.

          '
        schema:
          type: array
          items:
            type: string
            enum:
            - invoices
      security:
      - OAuth2:
        - read_external_bookings
        - read_invoices
      tags:
      - External Booking
      responses:
        '200':
          description: The external booking.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: externalBookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        title: Company Retreat
                        price:
                          net: '10.0'
                          gross: '11.0'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.0'
                            name: VAT
                        totalPrice:
                          net: '11.0'
                          gross: '12.1'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.1'
                            name: VAT
                        numberOfVisitors: 1
                        acceptedTerms: true
                        name: Earl McBride
                        company: ACME Inc.
                        billingAddress: 1422 Nuede Extension\nSpringfield, IL, 12345
                        structuredBillingAddress:
                          name: Earl McBride
                          company: ACME Inc.
                          fullAddress: 1422 Nuede Extension\nSpringfield, IL, 12345
                          street: 1422 Nuede Extension
                          postCode: '12345'
                          city: Springfield
                          state: IL
                          countryCode: US
                        taxId: 123456789A
                        phone: (959) 645-9532
                        email: fe@haos.eg
                        comments: we need catering
                        adminComments: make sure to air the room before
                        status: approved
                        accountingCode: EB1
                        canUpdate: true
                        discount:
                          code: SUMMER2024
                          name: Summer Sale
                          value: '10.0'
                          unit: percentage
                          amounts:
                          - net: '1.1'
                            gross: '1.21'
                            currency: EUR
                            taxes:
                            - rate: '10.0'
                              amount: '0.11'
                              name: VAT
                        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:
                        paymentMethod:
                          data: null
                        resource:
                          data:
                            id: 89da3cb66b5e6b39007690854kd66da4
                            type: externalResources
                        space:
                          data:
                            id: 99a12ca68b5e6bc9007890854kd368f2
                            type: spaces
                        invoices:
                          data:
                          - id: a07fed27-b35b-5c67-8367-3e52c397c528
                            type: invoices
                        contact:
                          data:
                            id: u2374d68h2j067d708qhj6whgn372872
                            type: contacts
        '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: Cancel as admin
      description: 'Cancel an external booking as an admin of a space.

        The external booking is marked as canceled

        and removed from the booking calendar (i.e. from any `/bookings` endpoints).


        Past bookings can only be canceled while they are still pending.


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

        '
      operationId: delete-external-booking
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking.
        schema:
          type: string
      security:
      - OAuth2:
        - write_external_bookings
      tags:
      - External Booking
      responses:
        '200':
          description: The canceled external booking.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: externalBookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        price:
                          net: '10.0'
                          gross: '11.0'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.0'
                            name: VAT
                        numberOfVisitors: 1
                        acceptedTerms: true
                        accountingCode: EB1
                        totalPrice:
                          net: '11.0'
                          gross: '12.1'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.1'
                            name: VAT
                        title: Company Retreat
                        name: Earl McBride
                        company: ACME Inc.
                        billingAddress: 1422 Nuede Extension
                        phone: (959) 645-9532
                        email: fe@haos.eg
                        comments: we need catering
                        canUpdate: false
                        status: canceled
                        canceledBy: space
                        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:
                        paymentMethod:
                          data: null
                        resource:
                          data:
                            id: 4a7dd89e-ff9c-5efd-897a-f40fb7138594
                            type: resources
                        space:
                          data:
                            id: 99a12ca68b5e6bc9007890854kd368f2
                            type: spaces
                        invoices:
                          data:
                          - id: a07fed27-b35b-5c67-8367-3e52c397c528
                            type: invoices
        '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.

                        '
        '409':
          description: The external booking is already canceled, or in the past and not pending.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - detail: This external booking is already canceled.
    patch:
      summary: Update booking
      description: 'Update an external booking.


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

        '
      operationId: update-external-booking
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking.
        schema:
          type: string
      security:
      - OAuth2:
        - write_external_bookings
      tags:
      - External Booking
      requestBody:
        description: Booking data to update.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/update-external-booking'
            examples:
              default:
                value:
                  data:
                    id: 8524f660-b2e6-583e-87ee-7c4ed4cdbfd9
                    type: externalBookings
                    attributes:
                      from: '2018-01-01T12:00:00Z'
                      to: '2018-01-01T14:00:00Z'
                      title: Company Retreat
                      adminComments: make sure to air the room before
                      customPrice:
                        net: '25.5'
      responses:
        '200':
          description: The updated external booking.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-booking'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: externalBookings
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        title: Company Retreat
                        price:
                          net: '10.0'
                          gross: '11.0'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.0'
                            name: VAT
                        totalPrice:
                          net: '11.0'
                          gross: '12.1'
                          currency: EUR
                          taxes:
                          - rate: '10.0'
                            amount: '1.1'
                            name: VAT
                        numberOfVisitors: 1
                        acceptedTerms: true
                        name: Earl McBride
                        company: ACME Inc.
                        billingAddress: 1422 Nuede Extension\nSpringfield, IL, 12345
                        structuredBillingAddress:
                          name: Earl McBride
                          company: ACME Inc.
                          fullAddress: 1422 Nuede Extension\nSpringfield, IL, 12345
                          street: 1422 Nuede Extension
                          postCode: '12345'
                          city: Springfield
                          state: IL
                          countryCode: US
                        taxId: 123456789A
                        phone: (959) 645-9532
                        email: fe@haos.eg
                        comments: we need catering
                        adminComments: make sure to air the room before
                        status: approved
                        accountingCode: EB1
                        canUpdate: true
                        discount:
                          code: SUMMER2024
                          name: Summer Sale
                          value: '10.0'
                          unit: percentage
                          amounts:
                          - net: '1.1'
                            gross: '1.21'
                            currency: EUR
                            taxes:
                            - rate: '10.0'
                              amount: '0.11'
                              name: VAT
                        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:
                        paymentMethod:
                          data: null
                        resource:
                          data:
                            id: 89da3cb66b5e6b39007690854kd66da4
                            type: externalResources
                        space:
                          data:
                            id: 99a12ca68b5e6bc9007890854kd368f2
                            type: spaces
                        invoices:
                          data:
                          - id: a07fed27-b35b-5c67-8367-3e52c397c528
                            type: invoices
                        contact:
                          data:
                            id: u2374d68h2j067d708qhj6whgn372872
                            type: contacts
        '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_bookings/{id}/cancellation:
    post:
      summary: Request cancellation
      description: 'Request to cancel an external booking as a visitor. This will not

        cancel the booking but send an email with a cancellation link

        to the email address used to make the booking.


        **Access**: Any user can request to cancel a booking.

        '
      operationId: external-booking-cancellation
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the booking.
        schema:
          type: string
      security:
      - OAuth2:
        - write_external_bookings
      tags:
      - External Booking
      responses:
        '204':
          description: Confirmation email is being sent. No changes to the external booking.
        '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.

                        '
        '409':
          description: The external booking is in the past or already canceled.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - detail: This external booking is already canceled.
  /external_bookings_preview:
    post:
      summary: Preview
      description: 'Preview creating an external booking.

        Depending on the resource pricing, returned attributes will contain either `appliedFixedRates` array, or `appliedDiscounts` and `appliedPriceCap`.


        **Access**: Any user can preview external bookings.

        '
      operationId: preview-external-booking
      security:
      - OAuth2:
        - read_external_resources
      tags:
      - External Booking
      responses:
        '200':
          description: The booking preview.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/external-booking-preview'
              examples:
                default:
                  value:
                    data:
                      id: b8f21a71ac8df98d29de357180d27358
                      type: externalBookingPreviews
                      attributes:
                        from: '2018-01-01T12:00:00Z'
                        to: '2018-01-01T14:00:00Z'
                        finalPrice:
                          net: '16.0'
                          gross: '17.6'
       

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