Nylas Room resources API

openapi: 3.2.0
info:
  title: Nylas Room resources API
  version: v3
  summary: The complete Nylas v3 API — Email, Calendar, Contacts, Notetaker, Scheduling, Administration, and Migration.
  description: The Nylas API is designed using the REST ideology to provide simple and predictable URIs to access and modify objects. Requests support standard HTTP methods like `GET`, `PUT`, `POST`, and `DELETE`, and standard status codes. Response bodies are always UTF-8 encoded JSON objects, unless explicitly documented otherwise. You can use the Nylas Postman collection to quickly start using the Nylas APIs. For more information, check out the Nylas Postman collection documentation.
  contact:
    url: https://www.nylas.com/
servers:
- url: https://api.us.nylas.com
  description: U.S.
- url: https://api.eu.nylas.com
  description: E.U.
security:
- ACCESS_TOKEN: []
- NYLAS_API_KEY: []
tags:
- name: Room resources
  description: 'The Nylas Contacts API allows you to return information about rooms that you can book for meetings, conferences, and other events.


    ## Room resource booking scopes


    The table below lists the Microsoft and Google scopes for room resource bookings. All scopes must include the fully qualified URI path for the provider, as defined in the table headers. These have been omitted from the scopes due to space constraints.


    The ☑️ character indicates the most restrictive scopes you can use for each provider.


    | Endpoint | Google Scopes

    `https://www.googleapis.com/auth/...` | Microsoft Scopes

    `https://graph.microsoft.com/...` |

    | :---------------------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |

    | **GET** `/v3/grants//resources` | `/admin.directory.resource.calendar.readonly` ☑️️ | `Place.Read.All` ☑️️ |


    For more information, see Using scopes to request user data.'
paths:
  /v3/grants/{grant_id}/resources:
    parameters:
    - schema:
        type: string
      name: grant_id
      in: path
      required: true
      description: 'ID of the grant to access. You can also use the email address associated with the grant, or use

        `/me/` to refer to the grant associated with an access token.'
      example: nyla@example.com
    get:
      summary: Return room resource information
      tags:
      - Room resources
      operationId: list-room-resources
      description: Returns information about all room resources.
      x-scopes:
        google:
          min: https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly
          others: ''
        microsoft:
          min: https://graph.microsoft.com/Place.Read.All
          others: ''
      security:
      - NYLAS_API_KEY: []
      - ACCESS_TOKEN: []
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/page_token'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --compressed --request GET \\\n  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/resources' \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --header 'Content-Type: application/json'"
      responses:
        '200':
          $ref: '#/components/responses/resources'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
components:
  schemas:
    resource:
      title: Room Resource
      type: object
      required:
      - email
      - object
      - capacity
      properties:
        building:
          $ref: '#/components/schemas/resource_building'
        capacity:
          $ref: '#/components/schemas/resource_capacity'
        email:
          $ref: '#/components/schemas/resource_email'
        floor_name:
          $ref: '#/components/schemas/resource_floor_name'
        floor_number:
          $ref: '#/components/schemas/resource_floor_number'
        floor_section:
          $ref: '#/components/schemas/resource_floor_section'
        name:
          $ref: '#/components/schemas/resource_name'
        object:
          type: string
          description: The object type (in this case, `room_resource`).
          example: room_resource
    resource_floor_number:
      title: Resource Floor Number
      type: integer
      description: (Microsoft only) The floor number where the room is located. Omitted when it's `0` or not set.
      example: 1
    resource_floor_name:
      title: Resource Floor Name
      type: string
      description: The name of the floor where the room is located.
      example: 1st Floor
    resource_capacity:
      title: Resource Capacity
      type: integer
      description: The number of people the room can seat. Always returned, and `0` when the provider has no capacity for the room.
      example: 5
    resource_building:
      title: Resource Building
      type: string
      description: The building where the room is located. For Google, this is the building ID rather than its display name.
      example: Building 1
    resource_floor_section:
      title: Resource Floor Section
      type: string
      description: (Google only) The section of the floor where the room is located.
      example: A
    common_response_with_cursor:
      properties:
        request_id:
          type: string
          description: The request ID.
        data:
          type: array
          description: The list of objects returned by the request.
          items:
            type: object
        next_cursor:
          type:
          - string
          - 'null'
          description: A cursor pointing to the next page of results for the request.
      example:
        request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
        next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4=
    resource_name:
      title: Resource Name
      type: string
      description: The display name of the room resource. Omitted when the provider doesn't return one.
      example: Training Room 1A
    resource_email:
      title: Resource Email
      type: string
      description: The email address associated with the room resource.
      example: conference-room@resources.google.com
  parameters:
    page_token:
      name: page_token
      in: query
      required: false
      schema:
        type: string
      description: 'An identifier that specifies which page of data to return. You can get this value from the

        `next_cursor` response field. See [Pagination](/docs/reference/api/#pagination) for more

        information.'
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 50
        maximum: 200
      description: 'The maximum number of objects to return. See [Pagination](/docs/reference/api/#pagination)

        for more information.'
  responses:
    '429':
      description: 'Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and

        says how long to wait, the `Retry-After` header gives that number of seconds. When the header

        is missing, retry with exponential backoff. See

        [429 rate limit errors by provider](/docs/api/errors/400-response/#429-rate-limit-errors-by-provider).'
      headers:
        Retry-After:
          description: 'The number of seconds to wait before retrying, rounded up. Present only when the provider, or

            Nylas for an Agent Account send, said how long to wait.'
          schema:
            type: integer
            example: 30
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The provider's own error, when the provider returned one.
          examples:
            Rate limited:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: rate_limit_error
                  message: Too many requests. If you see this error when fetching objects, set your limit=20 or lower. See http://nyl.as/429-tmr.
    resources:
      description: Room resource bookings
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/common_response_with_cursor'
            - properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/resource'
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
            - building: West Building
              capacity: 8
              email: training-room-1A@example.com
              floor_name: '7'
              floor_number: 7
              name: Training Room 1A
              object: room_resource
            next_cursor: OQ==
    '504':
      description: Provider Failure
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
          examples:
            Provider Failure:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: provider_error
                  message: Provider request timed out.
    '401':
      description: Unauthorized
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Unauthorized:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: unauthorized
                  message: Unauthorized
                  provider_error:
                    code: 401
                    message: Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
    '400':
      description: Bad Request
      content:
        application/json:
          schema:
            title: error
            type: object
            properties:
              request_id:
                type: string
                description: The request ID.
              error:
                type: object
                description: The response error object.
                properties:
                  type:
                    type: string
                    description: The error type.
                  message:
                    type: string
                    description: The error message.
                  provider_error:
                    type: object
                    description: The error from the provider.
          examples:
            Bad Request:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: invalid_request_error
                  message: error parsing request body
                  provider_error:
                    code: TargetIdShouldNotBeMeOrWhitespace
                    message: Id is malformed.
            Invalid Idempotency-Key:
              value:
                request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
                error:
                  type: api.invalid_idempotency_key
                  message: Idempotency-Key must be 256 characters or fewer.
  securitySchemes:
    IAM_API_KEY:
      type: http
      scheme: bearer
      bearerFormat: IAM API key
      description: An active, unexpired IAM credential of type `api_key` whose principal is active, has an Organization resource binding, and has the required IAM management permission. Use an existing IAM credential with these permissions, or [create your first management credential in the Dashboard](/docs/v3/auth/nylas-iam/manage-principals-with-api/#create-a-management-credential-in-the-dashboard). Application API keys (including legacy API keys) and provider OAuth tokens cannot authorize IAM management endpoints.
    ACCESS_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_ACCESS_TOKEN
      description: 'The Nylas **access token** for a specific grant. Issued as part of OAuth 2.1 flow token

        exchange.'
    NYLAS_API_KEY:
      scheme: bearer
      type: http
      bearerFormat: NYLAS_API_KEY
      description: 'The Nylas **API key** provides application-level access to APIs and all grants. You can

        generate these from the Dashboard. Learn more about [authorizing requests](/docs/v3/auth/).'
    SCHEDULER_SESSION_TOKEN:
      scheme: bearer
      type: http
      bearerFormat: Session ID
      description: The Nylas Scheduler **session ID** that Scheduler UI Components use to authorize API requests.
x-provenance:
  method: harvested
  publisher: Nylas
  source: https://developer.nylas.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)