openapi: 3.2.0 info: title: Nylas Calendar 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. contact: url: https://www.nylas.com/ x-provenance: method: harvested first_party: true publisher: Nylas source: https://developer.nylas.com/_spec-files/nylas-api.yaml harvested: '2026-08-21' sha256: 7ff001d571e163b1ffe22178741b59f813d8208ec878157a839a33dc2c13fd35 bytes: 1666223 note: 'Published by Nylas as the unified contract for the Nylas v3 API and stored verbatim; API Evangelist added only this provenance block. Submitted by the provider in api-evangelist/nylas#1 and verified against the live URL before harvest: OpenAPI 3.1.0, 118 paths, 208 operations, 174 component schemas, 100% of operations carrying summary, description, tag and a unique operationId, x-code-samples on 208 of 208. This document REPLACES a 22-operation scaffold API Evangelist derived from reading the documentation, now quarantined under openapi/_scaffold/.' x-evidence: - url: https://developer.nylas.com/_spec-files/nylas-api.yaml what: the published unified contract, harvested verbatim 2026-08-21 (200, text/yaml, 1,666,223 bytes) - url: https://developer.nylas.com/.well-known/api-catalog what: RFC 9727 linkset advertising that URL as service-desc for api.us.nylas.com and api.eu.nylas.com (200, application/linkset+json) 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: Calendar description: The Nylas Calendar API allows you to create and manage calendars, and access the events they contain. paths: /v3/grants/{grant_id}/calendars: parameters: - $ref: '#/components/parameters/grant_id' get: summary: Return all calendars tags: - Calendar operationId: get-all-calendars description: (Not supported for IMAP) Returns all calendars. x-scopes: google: min: https://www.googleapis.com/auth/calendar.readonly others: https://www.googleapis.com/auth/calendar microsoft: min: https://graph.microsoft.com/Calendars.Read others: https://graph.microsoft.com/Calendars.ReadWrite security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] parameters: - $ref: '#/components/parameters/field_selection' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/metadata_pair' - $ref: '#/components/parameters/page_token' x-code-samples: - lang: bash label: cURL source: "curl --request GET \\\n --url 'https://api.us.nylas.com/v3/grants//calendars' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nasync function fetchFiveAvailableCalendars() {\n try {\n const calendars = await nylas.calendars.list({\n identifier: \"\",\n queryParams: {\n limit: 5,\n },\n });\n\n console.log(\"Available Calendars:\", calendars);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchFiveAvailableCalendars();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\ncalendars = nylas.calendars.list(grant_id)\n\nprint(calendars)" - lang: ruby label: Ruby SDK source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t\tapi_key: \"\"\n)\n\n# Build the query without parameters\nlistCalendersQueryParams = {}\n\n# Build the query with parameters\nreturnFiveCalendars = {\n\tlimit: 5\n}\n\n# Get a list of calendars\ncalendars, _request_ids = nylas.calendars.list(identifier: \"\", \n\t\tquery_params: listCalendersQueryParams)\n\n# Loop the calendars\ncalendars.each {|calendar|\n\tputs(\"Name: #{calendar[:name]} | \" \\\n\t\t\t\"Description: #{calendar[:description]} | \" \\\n\t\t\t\"Is Read Only?: #{calendar[:read_only]} | \" \\\n\t\t\t\"Metadata: #{calendar[:metadata]}\")\n}\n\n# Build the event parameters with metadata\nCalendarsMetadata = {\n\tmetadata_pair: {\"key1\":\"This is my metadata\"}\n}\n\n# Get a list of calendars\ncalendars, _request_ids = nylas.calendars.list(identifier: \"\", \n\t\tquery_params: CalendarsMetadata)\n\nputs \"\" \ncalendars.each {|calendar|\n\tputs calendar\n}" - lang: kotlin label: Kotlin SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.resources.Calendars\n\nfun main(args: Array) {\n\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n // Build the query without parameters\n val calendarQueryParams: ListCalendersQueryParams = ListCalendersQueryParams()\n // Build the query with parameters\n val returnFiveCalendars: ListCalendersQueryParams = ListCalendersQueryParams(5)\n // Get all calendars\n val calendars: List = nylas.calendars().\n list(\"\",\n calendarQueryParams).data\n \n for(calendar in calendars){\n println(\"Id: \" + calendar.id +\n \" | Name: \" + calendar.name +\n \" | Description: \" + calendar.description +\n \" | Is Read Only?: \" + calendar.readOnly +\n \" | Metadata: \" + calendar.metadata)\n }\n\n // Build the event parameters with metadata\n val calendarsMetadata: ListCalendersQueryParams = ListCalendersQueryParams(\n metadataPair = mapOf(\"key1\" to \"This is my metadata\"))\n val calendarsMeta: List = nylas.calendars().\n list(\"\",\n calendarsMetadata).data\n println()\n println(calendarsMeta)\n}\n" - lang: java label: Java SDK source: "// Import packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.List;\nimport java.util.Map;\n\npublic class ReturnCalendars {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n // Initialize the Nylas client\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n // Build the query without parameters\n ListCalendersQueryParams listCalendersQueryParams = \n new ListCalendersQueryParams();\n // Build the query with parameters\n ListCalendersQueryParams returnFiveCalendars = new ListCalendersQueryParams.\n Builder().limit(5).build();\n\n // Get all calendars\n List calendars = nylas.calendars().\n list(\"\", listCalendersQueryParams).getData();\n\n // Loop the calendars\n for (Calendar calendar : calendars){\n // Print out the response\n System.out.println(\"Id: \" + calendar.getId() +\n \" | Name: \" + calendar.getName() +\n \" | Description: \" + calendar.getDescription() +\n \" | Is Read Only?: \" + calendar.getReadOnly() +\n \" | Metadata: \" + calendar.getMetadata());\n }\n\n // Build the event parameters with metadata\n ListCalendersQueryParams CalendarsMetadata = new ListCalendersQueryParams.\n Builder().\n metadataPair(\n Map.of(\"key1\", \n \"This is my metadata\")\n ).\n build();\n \n // Get all calendars that correspond to the metadata\n List metaCalendars = nylas.calendars().\n list(\"\", CalendarsMetadata).\n getData();\n // Print out the response\n System.out.println();\n System.out.println(metaCalendars);\n }\n}\n" responses: '200': $ref: '#/components/responses/calendars' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' post: summary: Create a calendar tags: - Calendar operationId: create-calendar description: Creates a calendar. x-scopes: google: min: https://www.googleapis.com/auth/calendar others: '' microsoft: min: https://graph.microsoft.com/Calendars.ReadWrite others: '' security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] parameters: - $ref: '#/components/parameters/field_selection' requestBody: $ref: '#/components/requestBodies/calendar_create' x-code-samples: - lang: bash label: cURL source: "curl --compressed --request POST \\\n --url 'https://api.us.nylas.com/v3/grants//calendars' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"My New Calendar\",\n \"description\": \"Description of my new calendar\",\n \"location\": \"Location description\",\n \"timezone\": \"America/Los_Angeles\"\n }'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nasync function createCalendar() {\n try {\n const calendar = await nylas.calendars.create({\n identifier: \"\",\n requestBody: {\n name: \"Nylas DevRel\",\n description: \"Nylas Developer Relations\",\n },\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ncreateCalendar();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\n\ncalendar = nylas.calendars.create(\n grant_id,\n request_body={\n \"name\": 'Nylas DevRel',\n \"description\": 'Nylas Developer Relations'\n }\n)\n\nprint(calendar)" - lang: ruby label: Ruby SDK source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"\")\n\nquery_params = {\n\tcalendar_id: \"\"\n}\n\nrequest_body = {\n\t\"name\": \"My New Calendar\",\n\t\"description\": \"Description of my new calendar\",\n\t\"location\": \"Location description\",\n\t\"timezone\": \"America/Toronto\",\n\t\"metadata\": { \"key1\":\"This is my metadata\" }\n}\n\ncalendar, _request_ids = nylas.calendars.create(\n\t\tidentifier: \"\", \n\t\trequest_body: request_body)\n\nputs calendar" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(apiKey = \"\")\n\n val requestBody = CreateCalendarRequest(\n \"My New Calendar\",\n \"Description of my new calendar\",\n \"Location description\",\n \"America/Toronto\",\n mapOf(\"key1\" to \"This is my metadata\")\n )\n\n val calendar: Response = nylas.calendars().\n create(\"\", requestBody)\n\n print(calendar.data)\n}\n" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\nimport java.util.Map;\n\npublic class CreateCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n CreateCalendarRequest requestBody = new CreateCalendarRequest.Builder(\"My New Calendar\")\n .description(\"Description of my new calendar\")\n .location(\"Location description\")\n .timezone(\"America/Toronto\")\n .metadata(Map.of(\"key1\", \"This is my metadata\"))\n .build();\n\n Response calendar = nylas.calendars().\n create(\"\", requestBody);\n\n System.out.println(calendar.getData());\n }\n}\n" responses: '200': $ref: '#/components/responses/calendar' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' /v3/grants/{grant_id}/calendars/{calendar_id}: parameters: - schema: type: string name: grant_id in: path required: true description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. - schema: type: string name: calendar_id in: path required: true description: 'ID of the calendar to access. You can use `primary` to refer to the primary calendar associated with a grant. Nylas recommends you URL-encode this field, or you might receive a [`404` error](/docs/api/errors/400-response/) if the ID contains special characters (for example, `#`).' get: summary: Return a calendar tags: - Calendar x-scopes: google: min: https://www.googleapis.com/auth/calendar.readonly others: https://www.googleapis.com/auth/calendar microsoft: min: https://graph.microsoft.com/Calendars.Read others: https://graph.microsoft.com/Calendars.ReadWrite responses: '200': $ref: '#/components/responses/calendar' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' operationId: get-calendars-id description: Returns the specified calendar. x-code-samples: - lang: bash label: cURL source: "curl --compressed --request GET \\\n --url 'https://api.us.nylas.com/v3/grants//calendars/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nasync function fetchCalendar() {\n try {\n const calendar = await nylas.calendars.find({\n identifier: \"\",\n calendarId: \"\",\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error fetching calendars:\", error);\n }\n}\n\nfetchCalendar();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\n\ncalendar = nylas.calendars.find(\n grant_id,\n \"\"\n)\n\nprint(calendar)" - lang: ruby label: Ruby SDK source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"\")\n\ncalendar, _request_ids = nylas.calendars.find(\n\t\tidentifier: \"\", \n\t\tcalendar_id: \"\"\n)\n\nputs calendar" - lang: java label: Java SDK source: "import com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class GetCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n Response calendar = nylas.calendars().find(\"\", \"\");\n\n System.out.println(\"Id: \" + calendar.getData().getId() +\n \" | Name: \" + calendar.getData().getName() +\n \" | Description: \" + calendar.getData().getDescription());\n }\n}" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(apiKey = \"\")\n val calendar: Response = nylas.calendars().find(\"\", \"\")\n\n println(\"Id: \" + calendar.data.id +\n \" | Name: \" + calendar.data.name +\n \" | Description: \" + calendar.data.description)\n}" security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] parameters: - $ref: '#/components/parameters/field_selection' put: summary: Update a calendar tags: - Calendar x-scopes: google: min: https://www.googleapis.com/auth/calendar others: '' microsoft: min: https://graph.microsoft.com/Calendars.ReadWrite others: '' responses: '200': $ref: '#/components/responses/calendar' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' operationId: put-calendars-id description: 'Updates the specified calendar. When you make a `PUT` request, Nylas replaces all data in the nested object with the information included in your request. For more information, see Updating objects.' x-code-samples: - lang: bash label: cURL source: "curl --compressed --request PUT \\\n --url 'https://api.us.nylas.com/v3/grants//calendars/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"name\": \"My New Calendar\",\n \"description\": \"Description of my new calendar\",\n \"location\": \"Location description\",\n \"timezone\": \"America/Los_Angeles\"\n }'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nasync function updateCalendar() {\n try {\n const calendar = await nylas.calendars.update({\n identifier: \"\",\n calendarId: \"\",\n requestBody: {\n name: \"Nylas DevRel Calendar\",\n description: \"Nylas Developer Relations\",\n },\n });\n\n console.log(\"Updated Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to update calendar:\", error);\n }\n}\n\nupdateCalendar();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\n\ncalendar = nylas.calendars.update(\n grant_id,\n calendar_id=\"\",\n request_body={\n \"name\": 'Nylas DevRel Calendar',\n \"description\": 'Nylas Developer Relations'\n }\n)\n\nprint(calendar)" - lang: ruby label: Ruby SDK source: "require 'nylas'\t\n\nnylas = Nylas::Client.new(api_key: \"\")\n\nrequest_body = {\n\t\"name\": \"\\\"New Test Calendar (changed)\\\"\",\n\t\"description\": \"\\\"this calendar has been updated!\\\"\",\n}\n\ncalendar, _request_ids = nylas.calendars.update(\n\t\tidentifier: \"\", \n\t\tcalendar_id: \"\").build();\n \n UpdateCalendarRequest requestBody = new UpdateCalendarRequest.Builder().\n name(\"My New Calendar\").\n description(\"Description of my new calendar\").\n location(\"Location description\").\n timezone(\"America/Los_Angeles\").\n build();\n \n Response calendar = nylas.calendars().update(\n \"\",\n \"\", \n requestBody);\n\n System.out.println(calendar.getData()); \n }\n}" - lang: kotlin label: Kotlin SDK source: "import com.nylas.NylasClient\nimport com.nylas.models.*\nimport com.nylas.resources.Calendars\n\nfun main(args: Array) {\n val nylas: NylasClient = NylasClient(apiKey = \"\")\n\n val requestBody = UpdateCalendarRequest.Builder().\n name(\"\\\"New Test Calendar (changed)\\\"\").\n description(\"\\\"this calendar has been updated!\\\"\").\n location(\"Location description\").\n timezone(\"America/Los_Angeles\").\n build()\n\n val calendar: Response = nylas.calendars().update(\n \"\",\n \"\",\n requestBody)\n \n print(calendar.data)\n}" security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] parameters: - $ref: '#/components/parameters/field_selection' requestBody: $ref: '#/components/requestBodies/calendar_update' delete: summary: Delete a calendar tags: - Calendar x-scopes: google: min: https://www.googleapis.com/auth/calendar others: '' microsoft: min: https://graph.microsoft.com/Calendars.ReadWrite others: '' responses: '200': $ref: '#/components/responses/200-delete' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '404': $ref: '#/components/responses/404' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' operationId: delete-calendars-id description: 'Deletes the specified calendar. You _cannot_ delete the primary calendar associated with an account (`"is_primary": true`).' x-code-samples: - lang: bash label: cURL source: "curl --compressed --request DELETE \\\n --url 'https://api.us.nylas.com/v3/grants//calendars/' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer ' \\\n --header 'Content-Type: application/json'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nasync function deleteCalendar() {\n try {\n const calendar = await nylas.calendars.destroy({\n identifier: \"\",\n calendarId: \"\",\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ndeleteCalendar();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\ncalendar_id = \"\"\n\nrequest = nylas.calendars.destroy(\n grant_id,\n calendar_id,\n)\n\nprint(request)" - lang: ruby label: Ruby SDK source: "# Load gems\nrequire 'nylas'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n api_key: \"\"\n)\n\n# Create new calendar\ncalendar, = nylas.calendars.destroy(identifier: \"\",\ncalendar_id: \"\")\n\n# Print calendar information\nputs calendar" - lang: java label: Java SDK source: "// Import packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\n\npublic class DeleteCalendar {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n // Delete the requested calendar\n try {\n nylas.calendars().destroy(\"\", \"\", null);\n\n System.out.println(\"Deleted successfully\");\n }\n catch(Exception e) {\n System.out.println(\"There was an error \" + e);\n }\n }\n}" - lang: kotlin label: Kotlin SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\nfun main(args: Array) {\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n try {\n val calendar: DeleteResponse = nylas.calendars().destroy(\"\", \"\")\n\n println(\"Deleted successfully\")\n }catch (e: NylasApiError){\n println(\"There was an error $e\")\n }\n}" security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] /v3/calendars/availability: post: summary: Get availability tags: - Calendar operationId: post-availability description: 'Returns availability information for the specified user or group of users. All participants'' email addresses must be associated with valid Nylas grants, and should be unique within their application.' x-scopes: google: min: https://www.googleapis.com/auth/calendar.readonly others: https://www.googleapis.com/auth/calendar microsoft: min: https://graph.microsoft.com/Calendars.Read others: https://graph.microsoft.com/Calendars.ReadWrite security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] requestBody: content: application/json: schema: type: object required: - duration_minutes - end_time - participants - start_time properties: availability_rules: type: object $ref: '#/components/schemas/availability_rules' duration_minutes: type: integer description: 'The duration of each time slot, in minutes. The duration must be a multiple of 5 minutes.' example: 30 end_time: type: integer description: 'The end of the time slot that Nylas checks availability for, in seconds using the Unix timestamp format. The time must be a multiple of 5 minutes.' example: 1659733200 interval_minutes: type: integer description: 'Nylas generates a time slot every `interval_minutes` (for example, every 30 minutes) and returns only slots when all participants are free. The interval must be a multiple of 5 minutes.' example: 30 participants: type: array description: A list of participants to get availability information for. items: type: object properties: calendar_ids: type: array description: 'A list of calendar IDs associated with the participant''s email address. If not defined, Nylas uses the participant''s primary calendar ID.' items: type: string example: - primary email: type: string description: 'The participant''s email address. The email address must be associated with a valid Nylas grant, and should be unique within its application.' example: nyla@example.com grant_id: type: string description: The participant's Nylas grant ID. open_hours: type: array description: 'An array of the participant''s open hours. Nylas searches for free time slots within these hours.' items: $ref: '#/components/schemas/availability_open_hours' only_specific_time_availability: type: boolean description: 'When `true`, Nylas checks availability only against this participant''s `specific_time_availability` entries and ignores their regular `open_hours`.' default: false example: true specific_time_availability: type: array description: 'An array of date and time ranges when the participant is available. Use with `only_specific_time_availability` set to `true` to restrict availability to only these windows.' items: $ref: '#/components/schemas/availability_specific_time_availability' round_to: type: integer description: 'Nylas rounds each time slot to the nearest `round_to` value. For example, if a time slot starts at 9:05a.m. and `round_to` is set to `15`, Nylas rounds it to 9:15a.m. The round to value must be a multiple of 5 minutes.' default: 15 example: 15 start_time: type: integer description: 'The beginning of the time slot that Nylas checks availability for, in seconds using the Unix timestamp format. The time must be a multiple of 5 minutes.' example: 1659366000 examples: - Collective request: participants: - email: nyla@example.com calendar_ids: - primary open_hours: - days: - 0 - 1 - 2 timezone: America/Toronto start: '9:00' end: '17:00' - email: leyah@example.com start_time: 1659366000 end_time: 1659733200 interval_minutes: 30 duration_minutes: 30 round_to: 15 availability_rules: availability_method: collective buffer: before: 15 after: 15 x-code-samples: - lang: bash label: cURL source: "curl --compressed --request POST \\\n\t--url 'https://api.us.nylas.com/v3/calendars/availability' \\\n\t--header 'Accept: application/json' \\\n\t--header 'Authorization: Bearer ' \\\n\t--header 'Content-Type: application/json' \\\n\t--data '{\n\t\t\"participants\": [\n\t\t\t{\n\t\t\t\t\"email\": \"leyah@example.com\",\n\t\t\t\t\"calendar_ids\": [\"leyah@example.com\"],\n\t\t\t\t\"open_hours\": [{\n\t\t\t\t\t\"days\": [0,1,2],\n\t\t\t\t\t\"timezone\": \"America/Toronto\",\n\t\t\t\t\t\"start\": \"9:00\",\n\t\t\t\t\t\"end\": \"17:00\",\n\t\t\t\t\t\"exdates\": []\n\t\t\t\t}]\n\t\t\t},\n\t\t\t{\n\t\t\t\t\"email\": \"nyla@example.com\",\n\t\t\t}\n\t\t],\n\t\t\"start_time\": 1600890600,\n\t\t\"end_time\": 1600999200,\n\t\t\"interval_minutes\": 30,\n\t\t\"duration_minutes\": 30,\n\t\t\"round_to\": 15,\n\t\t\"availability_rules\": {\n\t\t\t\"availability_method\": \"collective\",\n\t\t\t\"buffer\": {\n\t\t\t\t\"before\": 15,\n\t\t\t\t\"after\": 15\n\t\t\t},\n\t\t\t\"default_open_hours\": [\n\t\t\t\t{\n\t\t\t\t\t\"days\": [0,1,2],\n\t\t\t\t\t\"timezone\": \"America/Toronto\",\n\t\t\t\t\t\"start\": \"9:00\",\n\t\t\t\t\t\"end\": \"17:00\",\n\t\t\t\t\t\"exdates\": []\n\t\t\t\t},\n\t\t\t\t{\n\t\t\t\t\t\"days\": [3,4,5],\n\t\t\t\t\t\"timezone\": \"America/Toronto\",\n\t\t\t\t\t\"start\": \"10:00\",\n\t\t\t\t\t\"end\": \"18:00\",\n\t\t\t\t\t\"exdates\": []\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t}'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nconst email = \"\";\n\nasync function getCalendarAvailability() {\n try {\n const calendar = await nylas.calendars.getAvailability({\n requestBody: {\n startTime: 1630435200,\n endTime: 1630521600,\n durationMinutes: 15,\n participants: [{ email }],\n },\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ngetCalendarAvailability();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\nemail = \"\"\n\navailability = nylas.calendars.get_availability(\n request_body={\n \"start_time\": 1630435200,\n \"end_time\": 1630521600,\n \"duration_minutes\": 15,\n \"participants\": [{\"email\": email}]\n }\n)\n\nprint(availability)" - lang: ruby label: Ruby SDK source: "# Load gems\nrequire 'nylas'\nrequire 'date'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\t\tapi_key: \"\"\n)\n\n# Get today’s date\ntoday = Date.today\n\n# When do we start and end searching for availability\nstart_time = Time.local(today.year, today.month, today.day, 8, 0,0).strftime(\"%s\").to_i\nend_time = Time.local(today.year, today.month, today.day, 17, 0,0).strftime(\"%s\").to_i\n\n# Body of our request\nrequest_body = {\n\t\"participants\": [{\n\t\t\"email\": \"\",\n\t\t\"calendar_ids\": [\n\t\t\t\"\"\n\t\t],\n\t}],\n\t\"start_time\": start_time,\n\t\"end_time\": end_time,\n\t\"duration_minutes\": 60,\n}\n\n# Call the get_availability endpoint\navailable, _request_ids = nylas.calendars.get_availability(request_body: request_body)\n\n# Display available spots\navailable[:time_slots].each {|slots|\n\tputs \"From: #{Time.at(slots[:start_time]).to_datetime.strftime(\"%H:%M:%S\")}\" \\\n\t \" To: #{Time.at(slots[:end_time]).to_datetime.strftime(\"%H:%M:%S\")}\"\n}" - lang: java label: Java SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\n\nimport java.time.Instant;\nimport java.time.LocalDate;\nimport java.time.ZoneOffset;\nimport java.time.temporal.ChronoUnit;\nimport java.util.ArrayList;\nimport java.util.List;\nimport java.text.SimpleDateFormat;\n\npublic class get_availability {\n public static void main(String[] args) throws NylasSdkTimeoutError, NylasApiError {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n \n // Get today's date\n LocalDate today = LocalDate.now();\n // Our day starts at 8:00am\n Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);\n // Get time as a Unix timestamp\n long startTime = sixPmUtc.getEpochSecond();\n // Add 9 hours, so our day ends at 5:00pm\n Instant sixPmUtcPlus = sixPmUtc.plus(9, ChronoUnit.HOURS);\n long endTime = sixPmUtcPlus.getEpochSecond();\n\n List calendars = new ArrayList<>();\n calendars.add(\"\");\n\n AvailabilityParticipant participant = new AvailabilityParticipant.Builder(\"\")\n .calendarIds(calendars)\n .build();\n List participants = new ArrayList<>();\n participants.add(participant);\n\n GetAvailabilityRequest availability = new GetAvailabilityRequest.Builder(\n Math.toIntExact(startTime),\n Math.toIntExact(endTime),\n participants,\n 60).build();\n\n Response available = nylas.calendars().getAvailability(availability);\n\n assert available.getData().getTimeSlots() != null;\n\n for(TimeSlot times : available.getData().getTimeSlots()){\n String initDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((times.getStartTime() * 1000L)));\n String endDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((times.getEndTime() * 1000L)));\n \n System.out.println(\"From \" + initDate + \" To: \" + endDate);\n }\n }\n}" - lang: kotlin label: Kotlin SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\n// Import Java Packages\nimport java.text.SimpleDateFormat\nimport java.time.LocalDateTime\nimport java.time.ZoneOffset\n\nfun main(args: Array) {\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n // Get today's day\n var startDate = LocalDateTime.now()\n\n // Set time. As we're using UTC we need to add the hours in difference\n // from our own Timezone\n startDate = startDate.withHour(12);\n startDate = startDate.withMinute(0);\n startDate = startDate.withSecond(0);\n val endDate = startDate.withHour(21);\n\n val calendars : List = listOf(\"\")\n val participant = AvailabilityParticipant(\"\", calendars, null)\n val participants : List = listOf(participant)\n\n val request = GetAvailabilityRequest(startDate.toEpochSecond(ZoneOffset.UTC).toInt(),\n endDate.toEpochSecond(ZoneOffset.UTC).toInt(), participants, 60)\n\n val available : Response = nylas.calendars().\n getAvailability(request)\n\n for(slot in available.data.timeSlots!!){\n println(\"From: \" + SimpleDateFormat(\"HH:mm:ss\").format((slot.startTime * 1000L)) +\n \" to: \" + SimpleDateFormat(\"HH:mm:ss\").format((slot.endTime * 1000L)))\n }\n}" responses: '200': $ref: '#/components/responses/availability' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' /v3/grants/{grant_id}/calendars/free-busy: parameters: - schema: type: string name: grant_id in: path required: true description: ID of the grant to access. Use `/me/` to refer to the grant associated with an access token. post: summary: Get free/busy schedule tags: - Calendar x-scopes: google: min: https://www.googleapis.com/auth/calendar.readonly others: https://www.googleapis.com/auth/calendar microsoft: min: https://graph.microsoft.com/Calendars.Read others: https://graph.microsoft.com/Calendars.ReadWrite operationId: post-calendars-free-busy description: '(Not supported for iCloud) Returns the free/busy schedule for the specified list of email addresses. ### Keep in mind - The grant ID included in the request _must_ have access to view the provided email addresses'' free/busy data. This is usually configured by the provider. - All specified email addresses must use the same provider. - This endpoint always returns `200 OK`, even if one of the responses returns an error. Be sure to check for any errors in the list of responses. - Microsoft''s availability calculation is limited to a maximum of 1,000 entries per time slot for each email address included in the request. - The free/busy response does not include all-day room resource bookings on Google or Microsoft. - You can include up to 20 email addresses for Microsoft Graph, and up to 50 email addresses for Google in a single request.' x-code-samples: - lang: bash label: cURL source: "curl --compressed --request POST \\\n\t--url 'https://api.us.nylas.com/v3/grants//calendars/free-busy' \\\n\t--header 'Accept: application/json' \\\n\t--header 'Authorization: Bearer ' \\\n\t--header 'Content-Type: application/json' \\\n\t--data '{\n\t\t\"start_time\": 1682467200,\n\t\t\"end_time\": 1682550000,\n\t\t\"emails\": [\"leyah@example.com\"]\n\t}'" - lang: javascript label: Node.js SDK source: "import Nylas from \"nylas\";\n\nconst nylas = new Nylas({\n apiKey: \"\",\n apiUri: \"\",\n});\n\nconst email = \"\";\n\nasync function getFreeBusyCalendarInfo() {\n try {\n const calendar = await nylas.calendars.getFreeBusy({\n identifier: \"\",\n requestBody: {\n startTime: 1630435200,\n endTime: 1630521600,\n emails: [email],\n },\n });\n\n console.log(\"Calendar:\", calendar);\n } catch (error) {\n console.error(\"Error to create calendar:\", error);\n }\n}\n\ngetFreeBusyCalendarInfo();\n" - lang: python label: Python SDK source: "from nylas import Client\n\nnylas = Client(\n \"\",\n \"\"\n)\n\ngrant_id = \"\"\nemail = \"\"\n\nfree_busy = nylas.calendars.get_free_busy(\n grant_id,\n request_body={\n \"start_time\":1630435200,\n \"end_time\":1630521600,\n \"emails\":[email]\n }\n)\n\nprint(free_busy)" - lang: ruby label: Ruby SDK source: "# Load gems\nrequire 'nylas'\nrequire 'date'\n\n# Initialize Nylas client\nnylas = Nylas::Client.new(\n\tapi_key: \"\"\n)\n\n# Get today’s date\ntoday = Date.today\n\n# When do we start and end searching for availability\nstart_time = Time.local(today.year, today.month, today.day, 8, 0,0).strftime(\"%s\").to_i\nend_time = Time.local(today.year, today.month, today.day, 17, 0,0).strftime(\"%s\").to_i\n\n# Body of our request\nrequest_body = {\n\t\t\"emails\": [\n\t\t\"\"\n\t],\n\t\"start_time\": start_time,\n\t\"end_time\": end_time\n}\n\n# Call the get_availability endpoint\navailable, _request_ids = nylas.calendars.get_free_busy(identifier: \"\", \nrequest_body: request_body)\n\n# Display available spots\navailable.each {|time_slots|\n\ttime_slots[:time_slots].each {|slots|\n\t\tputs \"From: #{Time.at(slots[:start_time]).to_datetime.strftime(\"%H:%M:%S\")}\" \\\n \"To: #{Time.at(slots[:end_time]).to_datetime.strftime(\"%H:%M:%S\")}\"\n\t}\n}\n" - lang: java label: Java SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient;\nimport com.nylas.models.*;\n\n// Import Java packages\nimport java.text.SimpleDateFormat;\nimport java.time.Instant;\nimport java.time.LocalDate;\nimport java.time.ZoneOffset;\nimport java.time.temporal.ChronoUnit;\nimport java.util.ArrayList;\nimport java.util.List;\n\npublic class FreeBusy {\n public static void main(String[] args) throws Exception {\n NylasClient nylas = new NylasClient.Builder(\"\").build();\n\n LocalDate today = LocalDate.now();\n // Our day starts at 8:00am\n Instant sixPmUtc = today.atTime(13, 0).toInstant(ZoneOffset.UTC);\n int startTime = (int) sixPmUtc.getEpochSecond();\n // Add 10 hours, so our day ends at 6:00pm\n Instant sixPmUtcPlus = sixPmUtc.plus(10, ChronoUnit.HOURS);\n int endTime = (int) sixPmUtcPlus.getEpochSecond();\n\n // Add emails to check Free/Busy\n List emails = new ArrayList<>();\n emails.add(\"\");\n\n GetFreeBusyRequest request = new GetFreeBusyRequest(startTime, endTime, emails);\n\n Response> response = nylas.calendars().\n getFreeBusy(\"\", request);\n\n for(GetFreeBusyResponse freeBusy : response.getData()) {\n if (freeBusy.getObject() == FreeBusyType.FREE_BUSY) {\n GetFreeBusyResponse.FreeBusy freeBusyData = (GetFreeBusyResponse.FreeBusy) freeBusy;\n List times = freeBusyData.getTimeSlots();\n \n for(FreeBusyTimeSlot time : times){\n // Format dates in a readable way\n String startDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((time.getStartTime() * 1000L)));\n \n String endDate = new SimpleDateFormat(\"HH:mm:ss\").\n format(new java.util.Date((time.getEndTime() * 1000L)));\n \n // Print out the time slots\n System.out.println(\"From: \" + startDate + \" to: \" + endDate);\n }\n } else if (freeBusy.getObject() == FreeBusyType.ERROR) {\n GetFreeBusyResponse.FreeBusyError freeBusyError = (GetFreeBusyResponse.FreeBusyError) freeBusy;\n } else {\n throw new Exception(\"Unknown free busy type\");\n }\n }\n }\n}" - lang: kotlin label: Kotlin SDK source: "// Import Nylas packages\nimport com.nylas.NylasClient\nimport com.nylas.models.*\n\n// Import Kotlin/Java Packages\nimport java.lang.Exception\nimport java.time.LocalDateTime\nimport java.time.ZoneOffset\nimport java.util.*\n\nfun main(args: Array) {\n\n // Initialize Nylas client\n val nylas: NylasClient = NylasClient(\n apiKey = \"\"\n )\n\n // Get today's day\n var startDate = LocalDateTime.now()\n // Set time. As we're using UTC we need to add the hours in difference\n // from our own Timezone\n startDate = startDate.withHour(13);\n startDate = startDate.withMinute(0);\n startDate = startDate.withSecond(0);\n val endDate = startDate.withHour(23);\n val emails : List = listOf(\"\")\n\n // Make the request for Free/Busy\n val request : GetFreeBusyRequest = GetFreeBusyRequest(\n startDate.toEpochSecond(ZoneOffset.UTC).toInt(),\n endDate.toEpochSecond(ZoneOffset.UTC).toInt(), emails)\n\n // Call the Free/Busy endpoint\n val response : Response> = nylas.calendars().\n getFreeBusy(\"\", request)\n // Loop the list of Free/Busy objects\n for(freeBusy in response.data){\n if(freeBusy.getObject() == FreeBusyType.FREE_BUSY){\n // Get the free/busy data\n val freeBusyData: GetFreeBusyResponse.FreeBusy = freeBusy as\n GetFreeBusyResponse.FreeBusy\n // Get the busy time slots\n val times : List = freeBusyData.timeSlots\n // Loop the busy times\n for(time : FreeBusyTimeSlot in times){\n // Format dates in a readable way\n val startTime = Date(time.startTime.toLong() * 1000)\n val endTime = Date(time.endTime.toLong() * 1000)\n // Print out the time slots\n println(\"From: $startTime to $endTime\")\n }\n }else if(freeBusy.getObject() == FreeBusyType.ERROR){\n val freeBusyData: GetFreeBusyResponse.FreeBusyError = freeBusy as\n GetFreeBusyResponse.FreeBusyError\n }else{\n throw Exception(\"Unknown free busy type\")\n }\n }\n}\n" security: - NYLAS_API_KEY: [] - ACCESS_TOKEN: [] parameters: [] requestBody: $ref: '#/components/requestBodies/freebusy' responses: '200': $ref: '#/components/responses/freebusy' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '429': $ref: '#/components/responses/429' '504': $ref: '#/components/responses/504' components: responses: freebusy: description: Free/Busy Response content: application/json: schema: type: object properties: request_id: type: string description: The request ID. data: type: array description: 'An array of free/busy schedules. Nylas returns one free/busy schedule for each email address specified in the request.' items: type: object properties: email: type: string description: The participant's email address. time_slots: type: - array - 'null' description: 'An array of busy time slots. This field may be `null` when a free/busy lookup returns an error for a specific email address.' items: type: object properties: start_time: type: integer description: The beginning of a time slot, in seconds using the Unix timestamp format. end_time: type: integer description: The end of a time slot, in seconds using the Unix timestamp format. status: type: string description: The status of the time slot. object: type: string description: The object type (in this case, always `time_slot`). error: type: string description: 'If Nylas encounters an error fetching data for a participant, this field contains a description of the error.' object: type: string description: 'The object type. If the request succeeds, the value is `free_busy`. If the request fails, the value is `error`.' enum: - free_busy - error examples: free_busy_response: value: request_id: dd3ec9a2-8f15-403d-b269-32b1f1beb9f5 data: - email: user1@example.com time_slots: - start_time: 1690898400 end_time: 1690902000 status: busy object: time_slot - start_time: 1691064000 end_time: 1691067600 status: busy object: time_slot object: free_busy - email: user2@example.com error: Unable to resolve e-mail address user2@example.com to an Active Directory object. object: error '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. calendar: description: Calendar Response content: application/json: schema: allOf: - $ref: '#/components/schemas/common_response' - properties: data: $ref: '#/components/schemas/calendar' example: Calendar response example: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 data: description: Description of my new calendar hex_color: '#039BE5' hex_foreground_color: '#039BE5' id: 5d3qmne77v32r8l4phyuksl2x is_owned_by_user: true is_primary: true location: Los Angeles, CA metadata: your-key: value name: My New Calendar object: calendar owner_email: nyla@example.com read_only: false timezone: America/Los_Angeles notetaker: id: 5fa64c92-e840-4357-86b9-2aa364d35b87 name: Nylas Notetaker meeting_settings: video_recording: true audio_recording: true transcription: true transcription_settings: expected_languages: - en - es fallback_language: en rules: event_selection: - internal participant_filter: participants_gte: 5 participants_lte: 10 '429': description: Rate Limit 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: Not Found: value: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 error: type: rate_limit_error message: Too many requests, please try again shortly. availability: description: Return availability content: application/json: schema: allOf: - $ref: '#/components/schemas/common_response' - properties: data: $ref: '#/components/schemas/availability_response' examples: Return round-robin scheduling: value: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 data: order: - nyla@example.com - leyah@example.com time_slots: - emails: - leyah@example.com - nyla@example.com start_time: 1659367800 end_time: 1659369600 - emails: - nyla@example.com start_time: 1659376800 end_time: 1659378600 Return group Configuration availability: value: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 data: time_slots: - emails: - leyah@example.com - nyla@example.com start_time: 1659367800 end_time: 1659369600 capacity: 100 event_id": AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AeRryRUlhMECYNfAbiKd_mQABCjy6hAAA_20250409T193000Z calendar_id: primary master_id: AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AeRryRUlhMECYNfAbiKd_mQABCjy6hAAA - emails: - nyla@example.com start_time: 1659376800 end_time: 1659378600 capacity: 100 event_id": AAkALgAAAAAAHYQDEapmEc2byACqAC-EtegrfdsczUlhMECYNfAbiKd_mQABCjy6hAAA_20250409T193000Z calendar_id: primary master_id: AAkALgAAAAAAHYQDEapmEc2byACqAC-EfsrgdfeasECYNfAbiKd_mQABCjy6hAAA '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. '404': description: Not Found 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 raw error from the provider, if available properties: code: type: string message: type: string examples: Not Found: value: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 error: type: not_found_error message: requested object not found provider_error: code: MailboxNotEnabledForRESTAPI message: The mailbox is either inactive, soft-deleted, or is hosted on-premise. calendars: description: Calendars Response content: application/json: schema: allOf: - $ref: '#/components/schemas/common_response_with_cursor' - properties: data: type: array items: $ref: '#/components/schemas/calendar_common' example: Calendars response example: request_id: 5fa64c92-e840-4357-86b9-2aa364d35b88 data: - description: Description of my new calendar hex_color: '#039BE5' hex_foreground_color: '#039BE5' id: 5d3qmne77v32r8l4phyuksl2x is_owned_by_user: true is_primary: true location: Los Angeles, CA metadata: your-key: value name: My New Calendar object: calendar owner_email: nyla@example.com read_only: false timezone: America/Los_Angeles next_cursor: CigKGjRlaDdyNGQydTFqbWJ0bGo5a2QxdWJtdDZnGAEggIDAu7fw7bEYGg8IABIAGPjh2PGEi_0CIAEiBwgCEOqs6i4= '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. 200-delete: description: Delete Succeeded content: application/json: schema: type: object required: - request_id properties: request_id: type: string description: ID of the request. example: 5967ca40-a2d8-4ee0-a0e0-6f18ace39a90 parameters: field_selection: name: select in: query required: false schema: type: string description: 'Specify fields that you want Nylas to return, as a comma-separated list (for example, `select=id,updated_at`). This allows you to receive only the portion of object data that you''re interested in. You can use `select` to optimize response size and reduce latency by limiting queries to only the information that you need.' 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.' metadata_pair: name: metadata_pair in: query required: false schema: type: string description: 'Pass a metadata key/value pair (for example, `?metadata_pair=key1:value`) to search for metadata associated with objects. See [Metadata](/docs/reference/api/#metadata) 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.' grant_id: name: grant_id schema: type: string 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 schemas: calendar_owner_email: title: Owner email type: string description: '(Microsoft only) The email address of the account that owns the calendar. Use it to tell the grant''s own calendars apart from calendars shared with the grant. This field is read-only.' example: nyla@example.com calendar_common: title: Calendar type: object description: A Calendar object. properties: description: $ref: '#/components/schemas/calendar_description' grant_id: $ref: '#/components/schemas/grant_id' hex_color: $ref: '#/components/schemas/calendar_hex_color' hex_foreground_color: $ref: '#/components/schemas/calendar_hex_foreground_color' id: $ref: '#/components/schemas/id' is_owned_by_user: $ref: '#/components/schemas/is_owned_by_user' is_primary: type: - boolean description: If `true`, indicates that the calendar is the primary for the grant. location: $ref: '#/components/schemas/calendar_location' metadata: $ref: '#/components/schemas/metadata' name: $ref: '#/components/schemas/calendar_name' object: $ref: '#/components/schemas/object' example: calendar owner_email: $ref: '#/components/schemas/calendar_owner_email' read_only: $ref: '#/components/schemas/calendar_read_only' timezone: $ref: '#/components/schemas/calendar_timezone' calendar_location: type: string description: (Not supported for iCloud or EWS) The geographic location of the calendar, as free-form text. example: London, England meeting_settings_common: type: object description: A collection of settings for the Notetaker bot. properties: action_items: type: boolean description: 'When `true`, Notetaker generates a list of action items from the meeting. If `action_items` is `true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.' default: true example: true action_items_settings: type: object properties: custom_instructions: type: string description: 'A custom prompt to pass to Nylas'' AI model and specify settings for the list of action items it generates. `action_items` must be `true` to use this field.' example: Only return the 5 most important action items. audio_recording: type: boolean description: When `true`, Notetaker records the meeting's audio. default: true example: true leave_after_silence_seconds: type: integer description: 'The number of seconds of silence after which the Notetaker bot automatically leaves the meeting. This helps end recordings when meetings have concluded but participants haven''t disconnected the call. Must be between 10 and 3600 seconds (1 hour).' minimum: 10 maximum: 3600 default: 300 example: 360 summary: type: boolean description: 'When `true`, Notetaker generates a summary of the meeting. If `summary` is `true`, `video_recording`, `audio_recording`, and `transcription` must also be `true`.' default: true example: true summary_settings: type: object properties: custom_instructions: type: string description: 'A custom prompt to pass to Nylas'' AI model and specify settings for the summary it generates. `summary` must be `true` to use this field.' example: Return this summary in the MEDPIC sales methodology. transcription: type: boolean description: 'When `true`, Notetaker transcribes the meeting''s audio. If `transcription` is `true`, `video_recording` and `audio_recording` must also be `true`.' default: true example: true video_recording: type: boolean description: When `true`, Notetaker records the meeting's video. default: true example: true grant_id: title: Grant ID type: string description: The ID of grant for the connected user. example: 41009df5-bf11-4c97-aa18-b285b5f2e386 readOnly: true 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 calendar_sync: type: object properties: meeting_settings: $ref: '#/components/schemas/meeting_settings' name: type: string description: The display name for the Notetaker bot. default: Nylas Notetaker example: Nylas Notetaker rules: type: object description: Rules for when the Notetaker bot should join a meeting. properties: event_selection: type: array items: type: string enum: - all - external - internal - own_events - participant_only x-enum-descriptions: all: Join all events with meeting links. external: Join all events where the host's domain differs from any participant's domain. internal: Join all events where the host's domain matches all participants' domains. own_events: Join all events where the user is the host. participant_only: Join all events where the user is a participant, but not the host. description: 'Specify the types of events Notetaker should join. - "all": Join all events with meeting links. - "external": Join all events where the host''s domain differs from any participant''s domain. - "internal": Join all events where the host''s domain matches all participants'' domains. - "own_events": Join all events where the user is the host. - "participant_only": Join all events where the user is a participant, but not the host.' example: - internal participant_filter: type: object description: 'Specify filters to determine which events Notetaker should join, based on the number of participants. If you don''t specify any settings, a Notetaker joins meetings regardless of participants.' properties: participants_gte: type: integer description: 'Join all events where the number of participants is greater than or equal to the specified value.' example: 5 participants_lte: type: integer description: 'Join all events where the number of participants is less than or equal to the specified value.' example: 5 id: title: ID type: string minLength: 1 description: A globally unique object identifier for Microsoft accounts. An email address for Google accounts. example: 5d3qmne77v32r8l4phyuksl2x, nyla@example.com calendar_name: type: string description: The name of the calendar. example: My New Calendar calendar_timezone: title: Calendar timezone type: string description: '(Google and virtual calendars only) An [IANA timezone database](https://en.wikipedia.org/wiki/Tz_database) formatted string (for example, `America/New_York`).' example: America/Los_Angeles calendar_hex_color: title: Background color hex code type: string description: '(Not supported for iCloud or EWS) The background color of the calendar, in hexadecimal format (for example, `#0099EE`). When empty, Nylas uses the default background color. You can set or modify this value using a `PUT` request only.' example: '#039BE5' availability_specific_time_availability: description: A specific date and time range when the participant is available. type: object required: - date - start - end - timezone properties: date: type: string description: The date in `YYYY-MM-DD` format. example: '2026-03-18' end: type: string description: The end time in `HH:MM` format (24-hour). example: '17:00' start: type: string description: The start time in `HH:MM` format (24-hour). example: 09:00 timezone: type: string description: The participant's IANA timezone for this availability window. example: America/Toronto availability_buffer: title: buffer type: object properties: before: type: integer description: 'The amount of buffer time to add before meetings, in increments of five minutes. For example, if an account has a meeting scheduled from 10:00–11:00a.m., and you set a `before` buffer of 30 minutes, Nylas treats 9:30–11:00a.m. as busy. This value must be between 0 and 120, and must be divisible by 5.' default: 0 minimum: 0 maximum: 120 after: type: integer description: 'The amount of buffer time to add after meetings, in increments of five minutes. For example, if an account has a meeting scheduled from 10:00–11:00a.m., and you set an `after` buffer of 15 minutes, Nylas treats 10:00–11:15a.m. as busy. This value must be between 0 and 120, and must be divisible by 5.' default: 0 minimum: 0 maximum: 120 calendar_hex_foreground_color: title: Foreground color hex code type: string description: '(Google only) The foreground color of the calendar, in hexadecimal format (for example, `#0099EE`). When empty, Nylas uses the default foreground color. You can modify this value using a `PUT` request only.' example: '#039BE5' calendar_read_only: title: Read-only setting type: boolean description: 'Set by the provider. If `true`, indicates that the calendar is read-only. If the calendar is read-only, all of its events have `read_only` set to `true`. This field _cannot_ be modified.' availability_response: description: The response to a successful request to get availability for a participant. type: object properties: order: type: array items: type: string description: (Round-robin events only) The order of participants in line to attend the proposed meeting. time_slots: type: - array - 'null' items: $ref: '#/components/schemas/availability_time_slot' description: 'An array of the available time slots when you can create a meeting using the requested settings. This field may be `null` if no time slots are available. Treat `null` the same as an empty array.' metadata: title: Metadata type: object description: 'The metadata associated with the object. For more information, see [Metadata](/docs/reference/api/#metadata).' additionalProperties: type: string description: A key-value pair. maxLength: 500 maxProperties: 50 availability_open_hours: description: A time block when a participant is available for meetings. type: object title: Open Hours examples: [] properties: days: type: array description: 'The days of the week that the open hours settings are applied to. Sunday corresponds to `0`, and Saturday corresponds to `6`.' items: type: integer enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6 example: - 0 - 1 - 2 timezone: type: string minLength: 1 description: The calendar's time zone as an [IANA-formatted](https://en.wikipedia.org/wiki/Tz_database) string. example: America/Chicago start: type: string minLength: 1 description: 'The start time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes. The minimum start time is `0:00`, and the maximum is `23:49`.' example: '10:00' end: type: string minLength: 1 description: The end time for the open hours settings, in 24-hour time format. Nylas omits leading zeroes. example: '14:00' exdates: type: array description: A list of dates that Nylas excludes from the account's open hours, in `YYYY-MM-DD` format. items: type: string example: - '2006-01-18' meeting_settings: allOf: - $ref: '#/components/schemas/meeting_settings_common' - type: object properties: transcription_settings: type: object nullable: true description: "Optional settings that tune how Notetaker transcribes audio. `transcription` must be\n`true` for these settings to take effect. Provide any combination of the fields below.\n\nThe fields fall into two independent groups:\n\n- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic\n language detection. This declares the languages you expect; it does not translate\n transcripts or force the recording into a specific language.\n- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward\n domain-specific terms such as names, acronyms, and product names.\n\nSet on individual Notetakers, on calendar sync, or on event sync. When set on a calendar,\nevents inherit the value unless the event's own request overrides it. Send `null` or `{}`\nto clear inherited settings and return to default transcription behavior.\n\nSee [Set transcription languages](/docs/v3/notetaker/#set-transcription-languages) for\nsupported language codes and validation rules." properties: expected_languages: type: array description: 'Language codes the audio is expected to contain. Optional. When provided, it must contain at least one supported code and cannot be `null` or empty. When omitted, transcription considers all supported languages.' minItems: 1 items: type: string example: - en - es fallback_language: type: string description: 'Language to use if Notetaker does not detect one of the `expected_languages`. Optional. When `expected_languages` is set, the fallback must be one of those codes. When `expected_languages` is omitted, transcription considers all supported languages and the fallback may be any supported code. When `fallback_language` is omitted, the transcriber auto-detects the language. The field is not stored, so responses do not return it.' example: en keywords: type: array description: 'Domain-specific terms that bias transcription toward recognizing them correctly, such as names, acronyms, and product names. Optional. Up to 200 terms; each term must be 1 to 200 characters and cannot contain control characters. Cannot be `null`.' maxItems: 200 items: type: string maxLength: 200 example: - Nylas - AssemblyAI use_speaker_names_as_keywords: type: boolean description: 'When `true`, Notetaker adds known speaker names to the keyword set so they are transcribed accurately. Optional. Cannot be `null`.' example: true freebusy_request: title: free-busy type: object required: - start_time - end_time - emails properties: start_time: type: integer description: 'The start of a time block, in seconds using the Unix timestamp format. Nylas uses `start_time` and `end_time` to assess the specified account''s free/busy schedule.' example: 1690862400 end_time: type: integer description: 'The end of a time block, in seconds using the Unix timestamp format. Nylas uses `start_time` and `end_time` to assess the specified account''s free/busy schedule. For Google and EWS accounts, Nylas can query a timespan of up to 3 months from the `start_time`. For Microsoft Graph accounts, Nylas can query a timespan of up to 62 days from the `start_time`.' example: 1691208000 emails: type: array description: A list of email addresses to check the free/busy schedules for. items: type: string tentative_as_busy: type: boolean default: true description: When `true`, Nylas treats tentative events as busy. common_response_with_cursor: properties: request_id: type: string description: The request ID. data: type: object description: The response 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= object: type: string description: The type of object. is_owned_by_user: title: Is Owned By User type: boolean description: If `true`, indicates that the user owns the calendar. This field can't be modified once set. availability_time_slot: title: TimeSlot type: object properties: emails: type: - array - 'null' description: A list of participant email addresses for this time slot. This field may be `null`. Treat `null` the same as an empty array. items: type: string start_time: type: integer description: The start of a time slot, in seconds using the Unix timestamp format. end_time: type: integer description: The end of a time slot, in seconds using the Unix timestamp format. event_id: type: string description: (Group Events Only). The event ID of the group event master_id: type: string description: (Group Events Only). The master ID of the recurring group event calendar_id: type: string description: (Group Events Only). The calendar ID of the group event calendar: allOf: - $ref: '#/components/schemas/calendar_common' - properties: notetaker: $ref: '#/components/schemas/calendar_sync' calendar_description: title: Calendar description type: string description: (Not supported for iCloud or EWS) A brief description of the calendar. example: Junior sports league carpool drivers availability_rules: title: '' type: object properties: availability_method: type: string default: max-availability enum: - collective - max-fairness - max-availability buffer: type: object description: 'The amount of buffer time Nylas adds around existing meetings, in minutes. For example, if an account has a meeting scheduled from 10:00–11:00a.m., and you set a buffer of 30 minutes, Nylas treats 9:30–11:30a.m. as busy.' $ref: '#/components/schemas/availability_buffer' default_open_hours: type: array description: 'A default set of open hours to apply to all participants. You can overwrite these open hours for individual participants by specifying `open_hours` on the Participant object.' items: $ref: '#/components/schemas/availability_open_hours' round_robin_group_id: type: string description: 'The ID on events that Nylas considers when calculating the order of round-robin participants. This is used for both max-fairness and max-availability calculations. To calculate participant order correctly, set the metadata key `key5` to the same value on any events you want to consider for the current set of round-robin participants. You can set this key to any value that helps you identify events used to calculate availability in this group (for example, `new_subscriber_onboarding`).' tentative_as_busy: type: boolean default: true description: (Microsoft and EWS only) When `true`, Nylas treats tentative events as busy. requestBodies: calendar_create: content: application/json: schema: type: object required: - name properties: description: $ref: '#/components/schemas/calendar_description' location: $ref: '#/components/schemas/calendar_location' metadata: $ref: '#/components/schemas/metadata' name: $ref: '#/components/schemas/calendar_name' notetaker: $ref: '#/components/schemas/calendar_sync' timezone: $ref: '#/components/schemas/calendar_timezone' example: description: Calendar for work events. location: Los Angeles name: Work Calendar notetaker: name: Nyla's Notetaker meeting_settings: action_items: true action_item_settings: custom_instructions: Only return the 5 most important action items. audio_recording: true summary: true summary_settings: custom_instructions: Return this summary in the MEDPIC sales methodology. transcription: true transcription_settings: expected_languages: - en - es fallback_language: en video_recording: true rules: event_selection: - internal participant_filter: participants_gte: 5 participants_lte: 10 timezone: America/Los_Angeles freebusy: content: application/json: schema: $ref: '#/components/schemas/freebusy_request' example: start_time: 1633698000 end_time: 1633698000 emails: - user1@example.com - user2@example.com calendar_update: content: application/json: schema: type: object properties: description: $ref: '#/components/schemas/calendar_description' hex_color: $ref: '#/components/schemas/calendar_hex_color' hex_foreground_color: $ref: '#/components/schemas/calendar_hex_foreground_color' location: $ref: '#/components/schemas/calendar_location' metadata: $ref: '#/components/schemas/metadata' name: type: string description: 'The name of the calendar. Microsoft doesn''t allow you to update the name of a user''s primary calendar.' example: My Updated Calendar timezone: $ref: '#/components/schemas/calendar_timezone' notetaker: $ref: '#/components/schemas/calendar_sync' example: name: My New Calendar description: Description of my new calendar location: Location description timezone: America/Los_Angeles hex_color: '#039BE5' notetaker: name: Nylas Notetaker meeting_settings: video_recording: true audio_recording: true transcription: true transcription_settings: expected_languages: - en - es fallback_language: en rules: event_selection: - internal securitySchemes: 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.