Developers
Availies is being built and is not open for sign-up yet. This page describes the API as it is built, so there are no keys to create today.
One set of operations serves every caller: the admin app with a member's session, a customer's own system with an API key, and an assistant acting for a member. What a member can do in the app, a key or an assistant with the same rights can do through the same operation.
Where to read
- API reference: all 176 operations, generated from the OpenAPI document (Availies API, version 0.0.0).
- Events: every body Availies sends to a webhook endpoint.
- Webhooks: signing, delivery, retries, replay and reporting back.
- Lookups: how Availies asks your system who a visitor is.
- Assistants: the endpoint an assistant connects to, and which assistants may.
The basics
-
Operations live under
/v1. A member's session works on the app's hostname, and API keys work onapi.availies.com. The operations are the same. - The body is JSON. Times are ISO 8601 in UTC. Ids are Availies' own prefixed ids and carry no meaning to read into. Every operation has a stable operation id.
- The path carries the major version. A new field or a new event type does not change it, so a caller ignores what it does not know. A breaking change gets a new major version, and both run for a period.
Signing in
- Session. The session cookie set by sign-in.
-
API key.
An API key in the Authorization header:
Bearer avk_live_.... Accepted on the API's hostname only, and never together with the session cookie. Every request counts against the key's limit and its account's. A key belongs to the account, not to the member who made it, and it cannot hold the permission to manage keys. A key with no expiry never expires. -
An API key starts with
avk_live_in production andavk_test_everywhere else, followed by 52 base32 characters. It is shown once. It may never expire, or it may expire at an instant chosen when it is made. It is made by an owner or an admin. A key cannot holdapi_keys.manage, so it cannot make or revoke keys. See createApiKey. - A key has scopes, and a scope is a permission name, the same names roles use. An empty list means no rights, and there is no wildcard. A key can be made only with scopes its maker holds.
- An API key can read only its own effective permission names through getOwnApiKeyPermissions, without a key-inventory permission.
-
After a lost booking-page message, send the original
#prefill=token in the JSON body of resolveLinkToken. The API key needsbookings.read_ownandbookings.read. A booking id may still await confirmation; an active token is only a snapshot. Read the booking or await its webhook before showing success or offering another booking. -
A request that carries both a session cookie and a bearer credential is refused with
invalid_request, and so is a bearer credential on any hostname but the API's. A bad bearer credential isunauthenticatedand never falls back to the cookie. - The account comes from the credential. A header or a body field that names an account is ignored.
-
Limits are per credential: 300 requests a minute for one key, and 600 a minute across one
account's keys. Past that the answer is
rate_limitedwith aRetry-Afterheader.
Retrying safely
-
Send an
Idempotency-Keyheader on every change that can be retried. Where the reference says the key is required, the request is refused without one. Choose the key once for each intent and send the same key on a retry. -
The same key with a different request answers
409id_conflict. A repeat answers with the resource read again, never a stored copy of the first answer, and with the headerIdempotency-Replayed: true. A repeat that arrives while the first is still running answers409request_in_progresswithRetry-After. A key is remembered for 24 hours. -
A change to a booking carries the version the caller last saw. If the booking has moved on, the
answer is
409version_conflictand nothing changes.
When a request is refused
Every refusal has one shape, RFC 9457 problem details, sent as application/problem+json.
A client reads code first, then reason, then the issue paths. It never
reads the wording of detail, which is for a person and may change.
| Field | Type | Always sent | Notes |
|---|---|---|---|
type
|
string | yes | |
title
|
string | yes | |
status
|
integer | yes | |
detail
|
string | yes | |
code
|
string | yes |
Values:
plan_required
,
invalid_request
,
invalid_json
,
unauthenticated
,
forbidden
,
approval_required
,
no_active_account
,
not_found
,
method_not_allowed
,
version_conflict
,
conflict
,
handle_taken
,
last_owner
,
id_conflict
,
slot_taken
,
request_in_progress
,
invalid_slot
,
export_too_large
,
visitor_data_too_large
,
payload_too_large
,
rate_limited
,
unsupported_media_type
,
internal_error
,
sign_in_unavailable
,
not_configured
,
provider_unavailable
,
lookup_unavailable
,
recovery_hold
,
handle_renamed_recently
.
|
request_id
|
string | yes | |
issues
|
array of object | no | |
issues[]
|
object | yes | |
issues[].path
|
string | yes | |
issues[].message
|
string | yes | |
reason
|
string | no |
Values:
meeting_ended
,
booking_not_confirmed
,
already_at_time
,
outcome_unchanged
,
meeting_not_started
,
reschedule_still_finishing
,
range_not_valid
,
host_required
,
collective_not_reassigned
,
already_with_host
,
not_restorable
,
archived
,
snapshot_unreadable
,
already_current
,
route_used
,
route_expired
,
link_expired
,
link_in_use
,
link_dead
,
link_changed
,
already_member
,
booking_not_possible
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
lookup_in_use
,
address_unverified
,
sign_up_closed
,
recent_sign_in_required
,
bookings_open
,
handle_mismatch
,
account_not_active
,
account_not_suspended
,
already_closing
,
not_deleting
,
account_being_removed
,
recovery_hold_off
.
|
Codes that call for a decision
| Status | Code | Meaning | What the caller does |
|---|---|---|---|
| 409 |
slot_taken
|
Someone else got it. | Offer other slots. |
| 409 |
id_conflict
|
Same client id or retry key, different request. | Fix the caller. |
| 409 |
request_in_progress
|
The same request is still running. | Wait as Retry-After says, then retry with the same key. |
| 409 |
version_conflict
|
The booking changed since you read it. | Read it again and decide again. |
| 409 |
conflict
|
Something else depends on what you are changing. | Read the detail and remove the dependency first. |
| 422 |
invalid_slot
|
The time is not offered. | Offer other slots. |
| 503 |
provider_unavailable
|
A calendar could not be reached. | Retry later. Never treat the time as free. |
| 429 |
rate_limited
|
Too many requests. | Wait for Retry-After, in full. |
Every code
plan_required
,
invalid_request
,
invalid_json
,
unauthenticated
,
forbidden
,
approval_required
,
no_active_account
,
not_found
,
method_not_allowed
,
version_conflict
,
conflict
,
handle_taken
,
last_owner
,
id_conflict
,
slot_taken
,
request_in_progress
,
invalid_slot
,
export_too_large
,
visitor_data_too_large
,
payload_too_large
,
rate_limited
,
unsupported_media_type
,
internal_error
,
sign_in_unavailable
,
not_configured
,
provider_unavailable
,
lookup_unavailable
,
recovery_hold
,
handle_renamed_recently
Every reason
Where one code covers several causes a client must tell apart, the body also carries
reason, a short code from this closed list.
meeting_ended
,
booking_not_confirmed
,
already_at_time
,
outcome_unchanged
,
meeting_not_started
,
reschedule_still_finishing
,
range_not_valid
,
host_required
,
collective_not_reassigned
,
already_with_host
,
not_restorable
,
archived
,
snapshot_unreadable
,
already_current
,
route_used
,
route_expired
,
link_expired
,
link_in_use
,
link_dead
,
link_changed
,
already_member
,
booking_not_possible
,
not_https
,
bad_port
,
ip_literal
,
special_name
,
own_zone
,
does_not_resolve
,
points_inward
,
could_not_check
,
lookup_in_use
,
address_unverified
,
sign_up_closed
,
recent_sign_in_required
,
bookings_open
,
handle_mismatch
,
account_not_active
,
account_not_suspended
,
already_closing
,
not_deleting
,
account_being_removed
,
recovery_hold_off