Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
contact:
email: support@aurinko.io
description: '## Introduction
The Aurinko API is a unified API platform allowing developers to quickly build integrations with
many mailbox providers and services like Google, Office 365, Outlook.com, MS Exchange, IMAP.
The unified API abstracts away differences between many email, calendar, contact, task APIs
to make it easy to connect and sync the mailbox data.
The Aurinko API''s focus is convenient and reliable data synchronization for all supported
data categories (email, calendar, contacts, tasks) so the API provides methods to receive changes/deltas
and be notified of the changes (through webhooks) in a unified manner. The API''s sync/deltas model
should allow developers to build reliable event based solutions easily.
The Aurinko API is built on HTTP. Our API is RESTful. It has predictable resource URLs.
It returns HTTP response codes to indicate errors. It also accepts and returns JSON in the HTTP body.
## API Authentication
When you sign up for an account, you are given a Client Id and Secret
for every application that you create. You use those to go through OAuth flows that allow you
to start syncing remote account data through Aurinko. An account OAuth flow can be started with
just the Client Id and the Client Secret will be required to obtain an account access token in the
"authorization code" flow ("implicit grant" flow does is secured by the "trusted domains" setting).
Aurinko offers two forms of authentication:
- `Basic ` - used for authentication flows and administrative requests made from the server side.
- `Bearer ` - used for working with an account data.
- `Api Key in Cookie` - for in-browser apps that use Aurinko as their backend API with user sessions.
- `Api Key in Header (X-Aurinko-Session)` - for server side apps that need user sessions
Never share your client secret or access token. Keep them guarded and secure.
## Getting Started Guide
If you have a use case you would like to implement, please consult us for feedback on the best API operations for the task.
Click here to visit our API Guides.'
termsOfService: https://www.aurinko.io/terms-of-service/
title: Aurinko.io Booking API
version: 1.0.0
servers:
- url: https://api.aurinko.io
description: Production server
security:
- AccountToken: []
- AppAuth: []
AccountIdHeader: []
- UserSessionHeader: []
AccountIdHeader: []
- UserSessionCookie: []
ClientIdHeader: []
AccountIdHeader: []
- AuthTypeHeader: []
ExchangeIdToken: []
ClientIdHeader: []
AccountIdHeader: []
tags:
- name: Booking
x-displayName: Booking (Accounts)
description: Booking profiles allow you to build calendar availability and meeting scheduling apps. List, create, update, and delete booking profiles associated with a calendar (Aurinko account). Gather availability information from a calendar and find time slots when the calendar owner is available. Schedule events for a calendar owner.
paths:
/v1/book/account/workHours:
get:
operationId: workHours
tags:
- Booking
summary: Get user work hours
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/WeekWorkSchedule'
'401':
$ref: '#/components/responses/UnauthorizedError2'
/v1/book/account/profiles:
post:
operationId: create
tags:
- Booking
summary: Create a booking profile
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BookingInDto'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BookingOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
get:
operationId: getAccBookings
tags:
- Booking
summary: Get booking profiles
parameters:
- schema:
default: 50
format: int32
type:
- integer
- 'null'
in: query
name: limit
description: page size
required: false
- schema:
default: 0
format: int32
type:
- integer
- 'null'
in: query
name: offset
description: return records offset by the given number
required: false
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BookingPage'
'401':
$ref: '#/components/responses/UnauthorizedError2'
/v1/book/account/profiles/{id}:
patch:
operationId: updateBooking
tags:
- Booking
summary: Update a booking profile
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: A booking id
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BookingUpdateDto'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BookingSuccessOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
get:
operationId: getBooking
tags:
- Booking
summary: Get a booking profile by id
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: A booking id
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BookingOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
delete:
operationId: deleteBooking
tags:
- Booking
summary: Delete a booking profile by id
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: A booking id
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BookingSuccessOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
/v1/book/account/profiles/{id}/meeting:
post:
operationId: bookingAccountCreateMeeting
tags:
- Booking
summary: Create a meeting
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: A booking id
required: true
- schema:
default: one
type:
- core.client.booking.bookingrequiredmode.bookingrequiredmode
- 'null'
$ref: '#/components/schemas/BookingRequiredMode'
in: query
name: required
description: a way to select times
required: false
- schema:
format: int64
type:
- integer
- 'null'
in: query
name: reserveForMinutes
description: Time in minutes, blocks the interval for a time (creates an unconfirmed reservation), the meeting is not created
required: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMeetingDto'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMeetingResponse'
'401':
$ref: '#/components/responses/UnauthorizedError2'
get:
operationId: bookingAccountMeetingTimes
tags:
- Booking
summary: Get available meeting times
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: A booking id
required: true
- schema:
default: one
type:
- core.client.booking.bookingrequiredmode.bookingrequiredmode
- 'null'
$ref: '#/components/schemas/BookingRequiredMode'
in: query
name: required
description: a way to select times
required: false
- schema:
format: date
type:
- string
- 'null'
in: query
name: fromDate
description: date to iterate a big time intervals
required: false
- schema:
type:
- string
- 'null'
in: query
name: intervalLength
description: Time period (in ISO-8601 format) to iterate a big time intervals
required: false
- schema:
type:
- string
- 'null'
in: query
name: pageToken
description: token to request all pages, if booking has many accounts
required: false
- in: query
name: limit
required: false
schema:
format: int32
type:
- integer
- 'null'
- in: query
name: offset
required: false
schema:
format: int32
type:
- integer
- 'null'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/BookingTimesOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
/v1/book/account/reservations/{id}/confirm:
post:
operationId: bookingAccountReservationConfirm
tags:
- Booking
summary: Convert an unconfirmed booking reservation to a calendar event
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: An unconfirmed reservation id
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmReservationOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
/v1/book/account/reservations/{id}:
delete:
operationId: bookingAccountReservationDelete
tags:
- Booking
summary: Cancel an unconfirmed booking reservation
parameters:
- schema:
format: int64
type: integer
in: path
name: id
description: An unconfirmed reservation id
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmSlotDeleteOutDto'
'401':
$ref: '#/components/responses/UnauthorizedError2'
components:
schemas:
CreateMeetingResponse:
type: object
properties:
created:
type: boolean
id:
type: string
description: The created calendar event ID, if event was created
ReservationId:
type: integer
format: int64
description: The unconfirmed reservation ID
groupXid:
type: string
description: Group external id for group booking
ConfirmReservationOutDto:
type: object
properties:
id:
type: string
description: The created calendar event ID, if event was created.
BookingInDto:
type: object
properties:
name:
type: string
description: Profile name used in calendar links to identify a profile.
example: aurDemo - https://calendar.aurinko.io/aurDemo
durationMinutes:
type: integer
description: Duration of the meeting in minutes.
example: 30
availabilityStep:
type: integer
description: Determines the interval at which new meeting slots are made available throughout the working hours. Allowed values are 5, 10, 15, 20, 30, 60.
startTime:
type: string
format: date-time
description: The beginning of the formation of intervals. Must be in the future, otherwise the current time will be used.
endTime:
type: string
format: date-time
description: The ending of the formation of intervals. If the time specified here is in the past, the intervals will be empty, regardless of the Start time parameter.
timeAvailableFor:
type: string
description: Time period (in ISO-8601 format) the profile is covering. For example, P3M (3 months), P4W (4 weeks), P5D (5 days).
example: P4W
subject:
type: string
description: Subject for events booked using this profile.
description:
type: string
description: Description for events booked using this profile.
location:
type: string
description: Location for events booked using this profile.
workHours:
$ref: '#/components/schemas/WeekWorkSchedule'
availabilityIntervals:
description: the hours of availability for a date range, it have priority over workHours.
$ref: '#/components/schemas/AvailabilityIntervals'
context:
type: string
description: Custom client data stored for the profile.
startConference:
type: boolean
description: Whether to create an online conference (hangoutsMeet, teamsForBusiness, etc.) for the event. Note, not all providers support creating conferences.
openMeetingUrl:
type: string
description: The value of the {{openMeetingUrl}} variable that can be used in the event description or subject.
BookingPage:
type: object
properties:
offset:
type: integer
totalSize:
type: integer
format: int64
done:
type: boolean
records:
type: array
items:
$ref: '#/components/schemas/BookingOutDto'
DayOfWeek:
type: string
enum:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
WeekWorkSchedule:
type: object
properties:
daySchedules:
type: array
items:
$ref: '#/components/schemas/DayWorkSchedule'
timezone:
type: string
AdditionalField:
type: object
properties:
name:
type: string
description: Substitution variable name
type:
type: string
description: Value type
default:
type: string
description: Default value
CreateMeetingDto:
type: object
properties:
time:
$ref: '#/components/schemas/SelectedMeetingTime'
groupXids:
type: array
items:
type: string
description: Group external id from available meeting times request
accountIds:
type: array
items:
type: integer
format: int64
description: Account id from available meeting times request
name:
type: string
description: Username of the person requesting the meeting
email:
type: string
description: Email of the person requesting the meeting, if not specified, an event will be created without an attendee
substitutionData:
type: object
description: Data for substitution instead of templates, key - value
additionalProperties:
type: string
BookingSuccessOutDto:
type: object
properties:
status:
type: string
enum:
- Ok
BookingTimesOutDto:
type: object
properties:
items:
type: array
description: List of available meeting slots.
items:
$ref: '#/components/schemas/BookingMeetingInterval'
startTime:
type: string
format: date-time
description: Start time of available meeting slots.
endTime:
type: string
format: date-time
description: End time of available meeting slots.
timeAvailableFor:
type: string
description: Time period (in ISO-8601 format) the profile is covering. For example, P3M (3 months), P4W (4 weeks), P5D (5 days).
example: P4W
durationMinutes:
type: integer
description: Length of meeting in minutes
availabilityStep:
type: integer
description: Determines the interval at which new meeting slots are made available throughout the working hours. Allowed values are 5, 10, 15, 20, 30, 60.
subject:
type: string
description: Subject for events booked using this profile.
primaryColor:
type: string
description: Primary Color, taken from the application settings.
secondaryColor:
type: string
description: The second Color, taken from the application settings.
additionalFields:
type: array
description: List of substitution variables like {{name}}, {{openMeetingUrl}},...
items:
$ref: '#/components/schemas/AdditionalField'
nextPageToken:
type: string
description: Next page token
nextFromDate:
type: string
format: date
description: Next fromDate to iterate a big time intervals
BookingOutDto:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description: Profile name used in calendar links to identify a profile.
example: aurDemo - https://calendar.aurinko.io/aurDemo
durationMinutes:
type: integer
description: Duration of the meeting in minutes.
example: 30
availabilityStep:
type: integer
description: Determines the interval at which new meeting slots are made available throughout the working hours. Allowed values are 5, 10, 15, 20, 30, 60.
startTime:
type: string
format: date-time
description: The beginning of the formation of intervals. Must be in the future, otherwise the current time will be used.
endTime:
type: string
format: date-time
description: The ending of the formation of intervals. If the time specified here is in the past, the intervals will be empty, regardless of the Start time parameter.
timeAvailableFor:
type: string
description: Time period (in ISO-8601 format) the profile is covering. For example, P3M (3 months), P4W (4 weeks), P5D (5 days).
example: P4W
subject:
type: string
description: Subject for events booked using this profile.
description:
type: string
description: Description for events booked using this profile.
location:
type: string
description: Location for events booked using this profile.
workHours:
$ref: '#/components/schemas/WeekWorkSchedule'
availabilityIntervals:
description: the hours of availability for a date range, it have priority over workHours.
$ref: '#/components/schemas/AvailabilityIntervals'
context:
type: string
description: Custom client data stored for the profile.
startConference:
type: boolean
description: Whether to create an online conference (hangoutsMeet, teamsForBusiness, etc.) for the event. Note, not all providers support creating conferences.
openMeetingUrl:
type: string
description: The value of the {{}openMeetingUrl}} variable that can be used in the event description or subject.
BookingRequiredMode:
type: string
enum:
- one
- all
AvailabilityInterval:
type: object
properties:
dateStartInclusive:
type: string
format: date
dateEndInclusive:
type: string
format: date
hours:
type: array
items:
$ref: '#/components/schemas/WorkingInterval'
SelectedMeetingTime:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
BookingUpdateDto:
type: object
properties:
name:
type: string
description: Profile name used in calendar links to identify a profile.
example: aurDemo - https://calendar.aurinko.io/aurDemo
durationMinutes:
type: integer
description: Duration of the meeting in minutes.
example: 30
availabilityStep:
type: integer
description: Determines the interval at which new meeting slots are made available throughout the working hours. Allowed values are 5, 10, 15, 20, 30, 60.
startTime:
type: string
format: date-time
description: The beginning of the formation of intervals. Must be in the future, otherwise the current time will be used.
endTime:
type: string
format: date-time
description: The ending of the formation of intervals. If the time specified here is in the past, the intervals will be empty, regardless of the Start time parameter.
timeAvailableFor:
type: string
description: Time period (in ISO-8601 format) the profile is covering. For example, P3M (3 months), P4W (4 weeks), P5D (5 days).
example: P4W
subject:
type: string
description: Subject for events booked using this profile.
description:
type: string
description: Description for events booked using this profile.
location:
type: string
description: Location for events booked using this profile.
workHours:
$ref: '#/components/schemas/WeekWorkSchedule'
availabilityIntervals:
description: the hours of availability for a date range, it have priority over workHours.
$ref: '#/components/schemas/AvailabilityIntervals'
context:
type: string
description: Custom client data stored for the profile.
startConference:
type: boolean
description: Whether to create an online conference (hangoutsMeet, teamsForBusiness, etc.) for the event. Note, not all providers support creating conferences.
openMeetingUrl:
type: string
description: The value of the {{openMeetingUrl}} variable that can be used in the event description or subject.
DayWorkSchedule:
type: object
properties:
dayOfWeek:
$ref: '#/components/schemas/DayOfWeek'
workingIntervals:
type: array
items:
$ref: '#/components/schemas/WorkingInterval'
WorkingInterval:
type: object
properties:
start:
type: string
pattern: ^\d{2}:\d{2}:\d{2}$
example: 09:00:00
end:
type: string
pattern: ^\d{2}:\d{2}:\d{2}$
example: '17:00:00'
AvailabilityIntervals:
type: object
properties:
intervals:
type: array
items:
$ref: '#/components/schemas/AvailabilityInterval'
ConfirmSlotDeleteOutDto:
type: object
properties:
status:
type: string
enum:
- Ok
BookingMeetingInterval:
type: object
properties:
start:
type: string
format: date-time
end:
type: string
format: date-time
groupXids:
type: array
items:
type: string
accountIds:
type: array
items:
type: integer
format: int64
responses:
UnauthorizedError2:
description: Authentication information is missing or invalid
headers:
WWW_Authenticate:
schema:
type: string
securitySchemes:
AppAuth:
type: http
scheme: basic
description: App-level basic authentication using Client ID and Client Secret that can be obtained at Aurinko Dashboard page.
AccountToken:
type: http
scheme: bearer
description: Account-level authentication with account token obtained using `/auth/authorize` endpoint.
UserSessionCookie:
type: apiKey
in: cookie
name: AUR{APPID}
description: Cookie-based user-level authentication
UserSessionHeader:
type: apiKey
in: header
name: X-Aurinko-Session
description: Token-based user-level authentication
ClientIdHeader:
type: apiKey
in: header
name: X-Aurinko-Client-Id
description: Client ID that can be obtained at Aurinko Dashboard page
AccountIdHeader:
type: apiKey
in: header
name: X-Aurinko-Account-Id
description: User account id
AuthTypeHeader:
type: apiKey
in: header
name: X-Aurinko-Auth-Type
description: 'Authentication type. Possible values: default, exchangeIdToken'
ExchangeIdToken:
type: http
scheme: bearer
bearerFormat: 'Exchange Identity Token (only with `X-Aurinko-Auth-Type: exchangeIdToken` header.)'
description: 'Authentication using Exchange Identity Token. To use this method `X-Aurinko-Auth-Type: exchangeIdToken` header should be used.'
x-tagGroups:
- name: OAuth Flow
tags:
- Auth
- Account
- User
- name: Account management
tags:
- Accounts
- Services
- Managed accounts
- name: Email
tags:
- Messages
- EmailSync
- Drafts
- EmailFolders
- EmailTracking
- FollowUpRobot
- name: Calendars
tags:
- Calendars
- Events
- CalSync
- FreeBusySchedule
- name: Scheduling
tags:
- Booking
- GroupBooking
- Availability
- name: Contacts
tags:
- Contacts
- ContSync
- name: Tasks
tags:
- TaskLists
- Tasks
- TaskSync
- name: Webhooks
tags:
- Webhooks
- name: Other
tags:
- Errors