Nylas Sessions API

openapi: 3.2.0
info:
  title: Nylas Sessions 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: Sessions
  description: 'Nylas Scheduler uses session IDs to authorize requests to the `/v3/scheduling/availability` and `/v3/scheduling/bookings` endpoints.


    When you create a session, you must include the ID of an existing Configuration object. Sessions are only required for private configurations (`requires_session_auth: true`).


    ## Time to live


    For security purposes, Nylas recommends you set the `time_to_live` value for each session and refresh the sessions as they expire.'
paths:
  /v3/scheduling/sessions:
    post:
      summary: Create a session
      tags:
      - Sessions
      operationId: post-sessions
      description: 'Creates a new short-lived session that you can pass to the Scheduling Component to enforce user

        authentication. Your request must include the ID of an existing Configuration object.'
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --compressed --request POST \\\n  --url \"https://api.us.nylas.com/v3/scheduling/sessions\" \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"configuration_id\": \"<SCHEDULER_CONFIGURATION_ID>\",\n    \"time_to_live\": 10\n  }'"
      - lang: javascript
        label: Node.js SDK
        source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n  apiKey: \"<NYLAS_API_KEY>\",\n  apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function createSession() {\n  try {\n    const session = await nylas.scheduler.sessions.create({\n      requestBody: {\n        configurationId: \"<CONFIGURATION_ID>\",\n        timeToLive: 30,\n      },\n    });\n\n    console.log(\"Session:\", session);\n  } catch (error) {\n    console.error(\"Error creating session:\", error);\n  }\n}\n\ncreateSession();\n"
      - lang: python
        label: Python SDK
        source: "from nylas import Client\n\nnylas = Client(\n    \"<NYLAS_API_KEY>\",\n    \"<NYLAS_API_URI>\",\n)\n\nsession = nylas.scheduler.sessions.create(\n    request_body={\n        \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n        \"time_to_live\": 30,\n    },\n)\n\nprint(\"Created session:\", session)\n"
      - lang: ruby
        label: Ruby SDK
        source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n  api_key: \"<NYLAS_API_KEY>\"\n)\n\nrequest_body = {\n  \"configuration_id\": \"<SCHEDULER_CONFIG_ID>\",\n  \"time_to_live\": 30\n}\n\nsession, _request_ids = nylas.scheduler.sessions.create(request_body: request_body)\n\nputs session"
      - lang: java
        label: Java SDK
        source: "import com.nylas.NylasClient;\nimport com.nylas.models.CreateSessionRequest;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\nimport com.nylas.models.Response;\nimport com.nylas.models.Session;\n\npublic class CreateSession {\n  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n    NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n    CreateSessionRequest requestBody = new CreateSessionRequest.Builder()\n        .configurationId(\"<CONFIGURATION_ID>\")\n        .timeToLive(30)\n        .build();\n\n    Response<Session> session = nylas.scheduler().sessions().create(requestBody);\n\n    System.out.println(\"Session: \" + session.getData());\n  }\n}\n"
      - lang: kotlin
        label: Kotlin SDK
        source: "import com.nylas.NylasClient\nimport com.nylas.models.CreateSessionRequest\n\nfun main() {\n  val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n  val requestBody = CreateSessionRequest.Builder()\n      .configurationId(\"<CONFIGURATION_ID>\")\n      .timeToLive(30)\n      .build()\n\n  val session = nylas.scheduler().sessions().create(requestBody)\n\n  println(\"Session: ${session.data}\")\n}\n"
      security:
      - NYLAS_API_KEY: []
      parameters: []
      requestBody:
        $ref: '#/components/requestBodies/session_create'
      responses:
        '200':
          $ref: '#/components/responses/session_create'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
  /v3/scheduling/sessions/{session_id}:
    parameters:
    - schema:
        type: string
      name: session_id
      in: path
      required: true
      description: The ID of the session to modify.
    delete:
      summary: Delete a session
      tags:
      - Sessions
      operationId: delete-session
      description: Deletes a specific session.
      x-code-samples:
      - lang: bash
        label: cURL
        source: "curl --compressed --request DELETE \\\n  --url \"https://api.us.nylas.com/v3/scheduling/sessions/<SCHEDULER_SESSION_ID>\" \\\n  --header 'Accept: application/json' \\\n  --header 'Authorization: Bearer <NYLAS_API_KEY>' \\\n  --header 'Content-Type: application/json' "
      - lang: javascript
        label: Node.js SDK
        source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n  apiKey: \"<NYLAS_API_KEY>\",\n  apiUri: \"<NYLAS_API_URI>\",\n});\n\nasync function deleteSession() {\n  try {\n    const result = await nylas.scheduler.sessions.destroy({\n      sessionId: \"<SESSION_ID>\",\n    });\n\n    console.log(\"Deleted session:\", result);\n  } catch (error) {\n    console.error(\"Error deleting session:\", error);\n  }\n}\n\ndeleteSession();\n"
      - lang: python
        label: Python SDK
        source: "from nylas import Client\n\nnylas = Client(\n    \"<NYLAS_API_KEY>\",\n    \"<NYLAS_API_URI>\",\n)\n\nresponse = nylas.scheduler.sessions.destroy(\n    session_id=\"<SESSION_ID>\",\n)\n\nprint(\"Session deleted:\", response)\n"
      - lang: ruby
        label: Ruby SDK
        source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n  api_key: \"<NYLAS_API_KEY>\"\n)\n\n_, request_ids = nylas.scheduler.sessions.destroy(session_id: \"<SCHEDULER_SESSION_ID>\")"
      - lang: java
        label: Java SDK
        source: "import com.nylas.NylasClient;\nimport com.nylas.models.DeleteResponse;\nimport com.nylas.models.NylasApiError;\nimport com.nylas.models.NylasSdkTimeoutError;\n\npublic class DeleteSession {\n  public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n    NylasClient nylas = new NylasClient.Builder(\"<NYLAS_API_KEY>\").build();\n\n    DeleteResponse result = nylas.scheduler().sessions().destroy(\"<SESSION_ID>\");\n\n    System.out.println(\"Deleted session: \" + result);\n  }\n}\n"
      - lang: kotlin
        label: Kotlin SDK
        source: "import com.nylas.NylasClient\n\nfun main() {\n  val nylas = NylasClient.Builder(\"<NYLAS_API_KEY>\").build()\n\n  val result = nylas.scheduler().sessions().destroy(\"<SESSION_ID>\")\n\n  println(\"Deleted session: $result\")\n}\n"
      security:
      - NYLAS_API_KEY: []
      responses:
        '200':
          $ref: '#/components/responses/session_delete'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '504':
          $ref: '#/components/responses/504'
components:
  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.
    session_create:
      description: Create a new scheduling session
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/common_response'
            - properties:
                data:
                  type: object
                  properties:
                    session_id:
                      type: string
                      description: The ID of the session
          example:
            request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
            data:
              session_id: AAAA-BBBB-1111-2222
    '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.
    session_delete:
      description: The response to a successful request to delete a scheduling session.
      content:
        application/json:
          schema:
            type: object
            properties:
              request_id:
                type: string
                description: The ID of the request
                example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90
    '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.
  schemas:
    common_response:
      properties:
        request_id:
          type: string
          description: The request ID.
        data:
          type: object
          description: The response object.
      example:
        request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88
  requestBodies:
    session_create:
      description: Create a new scheduling session
      content:
        application/json:
          schema:
            type: object
            properties:
              configuration_id:
                type: string
                description: The ID of the Scheduler Configuration object for the session. If you're using `slug`, `configuration_id` is not required.
                example: AAAA-BBBB-1111-2222
              slug:
                type: string
                description: The slug of the Scheduler Configuration object for the session. You can use `slug` instead of `configuration_id`.
                example: my-page-slug
              time_to_live:
                type: number
                description: The time to live for the session in minutes. The maximum value is `30`.
                default: 5
                example: 10
  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)