Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
All 92 tools →
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/nylas:nylas-availability-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nylas Availability 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: Availability
description: 'Nylas Scheduler uses the `/v3/scheduling/availability` endpoint to retrieve availability information. When you make a request, Nylas validates the provided session ID and uses it to retrieve the related Configuration object.
When a Configuration participant is an Agent Account, Scheduler reads busy time from that account''s primary calendar only. Set the participant''s `availability.calendar_ids` to `["primary"]` or to the Agent Account''s email address; additional calendars on the Agent Account don''t affect the returned slots.
## Availability scopes
The table below lists the Availability endpoints and which scopes they require. The table shortens the full scope URI for space reasons, so add the prefix for the provider when requesting scopes.
The ☑️ in each column indicates the most restrictive scope you can request for each provider and still use that API. More permissive scopes appear under the minimum option. If you''re already using one of the permissive scopes, you don''t need to add the more restrictive scope.
| Endpoint | Google Scopes
`https://www.googleapis.com/auth/...` | Microsoft Scopes
`https://graph.microsoft.com/...` |
| :--------------------------------- | :------------------------------------------------------ | :----------------------------------------------------- |
| **GET** `/scheduling/availability` | `/calendar.readonly` ☑️
`/calendar` | `Calendars.Read` ☑️
`Calendars.ReadWrite` |
For more information about scopes, see Using scopes to request user data.'
paths:
/v3/scheduling/availability:
parameters:
- schema:
type: string
name: start_time
in: query
required: true
description: The time from which to check availability, in seconds using the Unix timestamp format.
- schema:
type: string
name: end_time
in: query
required: true
description: The time until which to check availability, in seconds using the Unix timestamp format.
- schema:
type: string
name: configuration_id
in: query
required: false
description: 'The ID of the Configuration object used for calculating availability. If you''re using session
authentication (`requires_session_auth: true`), the `configuration_id` isn''t required.'
- schema:
type: string
name: slug
in: query
required: false
description: 'The Configuration object slug. You can use this with the `client_id` instead of using the
`configuration_id`. If you''re using session authentication (`requires_session_auth: true`) or
using the `configuration_id`, `slug` isn''t required.'
- schema:
type: string
name: client_id
in: query
required: false
description: 'The client ID that was used to create the Configuration object. Required only if you''re using
`slug`.'
- schema:
type: string
name: booking_id
in: query
required: false
description: 'The ID of the booking to reschedule, if you''re checking availability to reschedule a round-robin
booking. Required only if `availability_method` is `max-fairness` or `max-availability`. See
[Retrieve booking IDs](/docs/v3/scheduler/retrieve-booking-ids/) for more information.'
get:
summary: Get availability
tags:
- Availability
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: get-availability
description: 'Gets available time slots within the given time range, using the rules defined in the specified
Configuration object. If the Configuration `type` is `group`, Nylas returns only valid group events
within the time range, including recurring events.
Nylas validates the provided session ID and uses it to retrieve the related
Configuration object. If you created a public
Configuration, you don''t need to include the `Authorization` request header with a session ID, but
you do need to pass the Configuration object ID as a query parameter.'
x-code-samples:
- lang: bash
label: cURL (Public)
source: "curl --compressed --request GET \\\n --url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200&configuration_id=<SCHEDULER_CONFIG_ID>' \\\n --header 'Accept: application/json' \\\n --header 'Content-Type: application/json'"
- lang: bash
label: cURL (Private)
source: "curl --compressed --request GET \\\n --url 'https://api.us.nylas.com/v3/scheduling/availability?start_time=1709643600&end_time=1709665200' \\\n --header 'Accept: application/json' \\\n --header 'Authorization: Bearer <SCHEDULER_SESSION_ID>' \\\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 getAvailability() {\n try {\n const availability = await nylas.scheduler.availability.get({\n queryParams: {\n configurationId: \"<CONFIGURATION_ID>\",\n startTime: 1748908800,\n endTime: 1748995200,\n },\n });\n\n console.log(\"Availability:\", availability);\n } catch (error) {\n console.error(\"Error getting availability:\", error);\n }\n}\n\ngetAvailability();\n"
responses:
'200':
$ref: '#/components/responses/availability'
'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'
security:
- SCHEDULER_SESSION_TOKEN: []
components:
schemas:
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. Only returned for occurrences of a recurring group event.
calendar_id:
type: string
description: (Group Events Only). The calendar ID of the group event
capacity:
type: integer
description: (Group Events Only). The number of spots still available in the group event for this time slot. This is the event's capacity minus the guests who have already booked it.
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.'
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
responses:
'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.
'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.
'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.
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
'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.
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)