1KEY Developers
API reference

Sites

Base URL https://api.1keyplatform.dev/v1. Every endpoint below is generated from the OpenAPI contract, which you can download as openapi.yaml.

Log in to send these requests to your organization from this page.

Sites

The buildings your organization manages. Every hub is at a site.

GET /sites/{site_id}/concierge/sessions

List a site's concierge conversations

Needs the sites:read scope.

Newest first. No audio or transcript is kept.

Parameters

Name In Type Description
site_id required path string
limit optional query integer, 1–100, default 50
starting_after optional query string ID of the last item on the previous page.

Responses

200 A page of conversations.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /sites/{site_id}/outages

List a site's outages

Needs the hubs:read scope.

Times when at least half of the site's hubs, and two or more, were offline together for a minute or more: likely the building's network or power. Oldest first. A site with fewer than two hubs has none.

Parameters

Name In Type Description
site_id required path string
from optional query string ISO 8601 time with an offset. Defaults to 24 hours before to; at most 35 days before it.
to optional query string ISO 8601 time with an offset. Defaults to now.

Responses

200 The outages between from and to.
200 · example
{
  "data": [
    {
      "from": "2026-10-20T12:12:00Z",
      "offline": 2,
      "ongoing": false,
      "to": "2026-10-20T12:18:00Z"
    }
  ]
}

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /sites

List sites

Needs the sites:read scope.

Your organization's sites, oldest first.

Parameters

Name In Type Description
limit optional query integer, 1–100, default 50
starting_after optional query string ID of the last item on the previous page.
q optional query string Only sites whose name contains this, ignoring case.
include_test optional query boolean, default true false leaves test sites out.
expand optional query string Comma-separated. status adds each site's hubs now (status), trend its trend over range (trend). Both need hubs:read.
range optional query "24h" | "7d" | "30d" The trend's range: the last 24 UTC hours (hourly buckets), or the last 7 or 30 days (daily buckets), now included.
measures optional query string Comma-separated measures to include in each trend's buckets and totals (see TrendMeasures). Default: all.

Responses

200 A page of sites.
200 · example
{
  "data": [
    {
      "created_at": "2026-09-12T15:20:00Z",
      "hub_count": 2,
      "id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40",
      "location": null,
      "name": "120 Harbour St",
      "test": false,
      "time_zone": "America/Toronto"
    }
  ],
  "has_more": false
}

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
429 Too many requests. Retry after the Retry-After header.
POST /sites

Create a site

Needs the sites:write scope.

Body

name string, up to 100 characters · required
location object or null · optional
test boolean, default false · optional
time_zone string · optional

Responses

201 The new site. · returns a Site

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
GET /sites/{site_id}/concierge

Read a site's virtual concierge

Needs the sites:read scope.

Whether the site's intercoms offer the virtual concierge, its limits, and what it knows about the building. A site that never set one up answers the defaults, not enabled.

Parameters

Name In Type Description
site_id required path string

Responses

200 The profile. · returns a ConciergeProfile

Errors

401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PATCH /sites/{site_id}/concierge

Change a site's virtual concierge

Needs the sites:write scope.

Fields left out keep their values; profile is replaced whole.

Parameters

Name In Type Description
site_id required path string

Body

calls boolean · optional Whether the concierge can call a resident or the front desk from the intercom's directory, once the visitor confirms who. Off: it opens the Directory screen instead.
daily_sessions integer, 0–10000 · optional
enabled boolean · optional
idle_timeout_s integer, 5–120 · optional
knowledge string, up to 8000 characters · optional What it should know about the building beyond profile, as free text in its prompt. An empty string clears it.
languages array of "en" | "fr" | "es" · optional
max_concurrent integer, 1–20 · optional
max_session_s integer, 30–480 · optional
monthly_minutes integer, 0–1000000 · optional Minutes of conversation a calendar month across the site, at the site.
persona_bio string, up to 2000 characters · optional Facts about the person the character is modelled on, shared when a visitor asks. An empty string clears it.
persona_name string, up to 40 characters · optional
privacy_answer string, up to 500 characters · optional What the concierge answers when asked whether it records; null for default_privacy_answer. An empty string clears it.
profile ConciergeKnowledge · optional
pronunciations object · optional How to say words the concierge gets wrong: the written form to how it's said, at most 100, each at most 60 characters.
style string, up to 2000 characters · optional How the concierge speaks; null for the default. An empty string clears it.
voices object · optional The voice for each language: a voice name such as marin, or a Cartesia voice ID where the concierge speaks with Cartesia. A language left out takes the default. Read back with every language's voice.

Responses

200 The profile. · returns a ConciergeProfile

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /sites/{site_id}

Get a site

Needs the sites:read scope.

Parameters

Name In Type Description
site_id required path string
expand optional query string Comma-separated. hubs includes the site's hubs, status its hubs now, trend its trend over range. Each needs hubs:read.
range optional query "24h" | "7d" | "30d" The trend's range: the last 24 UTC hours (hourly buckets), or the last 7 or 30 days (daily buckets), now included.
measures optional query string Comma-separated measures to include in each trend's buckets and totals (see TrendMeasures). Default: all.

Responses

200 The site. · returns a Site

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
PATCH /sites/{site_id}

Rename a site, or set its time zone and location

Needs the sites:write scope.

Parameters

Name In Type Description
site_id required path string

Body

location object or null · optional
name string, up to 100 characters · optional
test boolean · optional
time_zone string · optional

Responses

200 The updated site. · returns a Site

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.
GET /sites/{site_id}/concierge/usage

A site's concierge usage by day

Needs the sites:read scope.

The conversations that connected, by the day they started at the site, from from to to inclusive: at most 92 days, the last 30 by default.

Parameters

Name In Type Description
site_id required path string
from optional query string
to optional query string

Responses

200 The usage.

Errors

400 invalid_request The request is malformed or a field is invalid.
401 unauthenticated Missing, malformed, revoked or unknown API key.
403 insufficient_scope The key lacks the scope this operation needs.
404 not_found No such resource, or it is not your organization's.