Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
0d7d667
Publish the API versions and oldest apps a server serves, and name th…
davidmckayv Nov 18, 2026
707b6c7
Say the version refusal applies to /api/v2 operations only
davidmckayv Nov 18, 2026
3179768
Name the phone app and the Recorder on every request, and say Update …
davidmckayv Nov 18, 2026
d27a193
Name the web app on every request, and show what to update when it an…
davidmckayv Nov 18, 2026
0921225
Merge branch 'feat/version-check-web' into feat/version-check
davidmckayv Nov 18, 2026
b68f733
Merge branch 'feat/version-check-clients' into feat/version-check
davidmckayv Nov 18, 2026
a04650c
Keep the fixture's admin raise within what a server can serve its own…
davidmckayv Nov 18, 2026
00c38b2
Desktop names itself to every OpenBot and says when it or the OpenBot…
davidmckayv Nov 18, 2026
3e214f1
Merge branch 'feat/version-check' into feat/version-check-desktop
davidmckayv Nov 18, 2026
db0eb6a
Serve every app from the last 12 months, and add nothing for an OpenB…
davidmckayv Nov 18, 2026
dad1f4f
Say when an app must update because of a security problem
davidmckayv Nov 18, 2026
07f439a
Merge remote-tracking branch 'origin/main' into feat/version-check
davidmckayv Nov 18, 2026
6f40c3b
Read the OpenBot-Client header one way for the version check and the …
davidmckayv Nov 18, 2026
39ed4dd
Name the first release of each app that calls /api/v2
davidmckayv Nov 18, 2026
ea18620
Merge remote-tracking branch 'origin/main' into feat/version-check
davidmckayv Nov 18, 2026
6997a0f
Merge remote-tracking branch 'origin/main' into feat/version-check
davidmckayv Nov 18, 2026
6f5b23e
Merge remote-tracking branch 'origin/main' into feat/version-check
davidmckayv Nov 18, 2026
86d4497
Merge remote-tracking branch 'origin/main' into feat/version-check
davidmckayv Nov 18, 2026
0fe5a14
Desktop: Update OpenBot, running, when a launch finds it needs a newe…
davidmckayv Nov 18, 2026
ba40bed
Merge branch 'main' into feat/version-check
davidmckayv Nov 18, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/desktop.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,10 @@ name: Desktop
# it at runtime with an `expect`, so a bad row panics the window rather than failing a type check.
on:
pull_request:
paths: ["desktop/**", "shared/harnesses.json", "shared/marks/**", "shared/recorder-extension.json", "package.json", ".github/workflows/desktop.yml", ".github/workflows/desktop-build.yml"]
paths: ["desktop/**", "shared/harnesses.json", "shared/marks/**", "shared/recorder-extension.json", "shared/fixtures/client-version/**", "package.json", ".github/workflows/desktop.yml", ".github/workflows/desktop-build.yml"]
push:
branches: [main]
paths: ["desktop/**", "shared/harnesses.json", "shared/marks/**", "shared/recorder-extension.json", "package.json", ".github/workflows/desktop.yml", ".github/workflows/desktop-build.yml"]
paths: ["desktop/**", "shared/harnesses.json", "shared/marks/**", "shared/recorder-extension.json", "shared/fixtures/client-version/**", "package.json", ".github/workflows/desktop.yml", ".github/workflows/desktop-build.yml"]
workflow_call:
secrets:
OPENBOT_GOOGLE_MODEL_OAUTH_CLIENT_SECRET:
Expand Down
89 changes: 88 additions & 1 deletion api/openapi.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ info:

An install for one person on one computer has no sign-in. It signs nobody in, so it has neither OAuth nor API keys, and the operations that manage keys and sessions answer 503 with the code SIGN_IN_UNAVAILABLE.

OpenBot's own apps name themselves on every request in the header `OpenBot-Client`: `<kind>/<version>`, where kind is web, desktop, mobile or recorder, such as `OpenBot-Client: desktop/1.1.0`. A header may name more than one, separated by spaces: OpenBot Desktop adds its own to the one its window's page sent. getDeployment says which API versions this OpenBot serves and the oldest release of each app it serves (minimumClients). Every other operation under /api/v2 refuses an app older than that with 400 and the code CLIENT_UPDATE_REQUIRED, whose problem names the app (client) and its minimum (minimumVersion) and whose detail tells the person to update OpenBot. When that minimum was raised because of a security problem in older releases, the problem also says security: true, and getDeployment lists it under securityMinimumClients. A program of your own need not send the header; without it nothing is refused for a version.

This file is the single source of truth: the clients, the server's types, the docs and the contract tests are all generated from it or checked against it. A change that breaks an existing client fails the pull request.
servers:
- url: http://127.0.0.1:3001
Expand Down Expand Up @@ -1690,7 +1692,7 @@ paths:
- Organization settings
operationId: getDeployment
summary: Read what this OpenBot offers
description: 'Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, how large an attached file may be, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it first. Signed in, it is answered in an organization the caller is a member of, and an organization they are not in, the organization `default` included, answers exactly as one that does not exist. Nobody signed in reads it in the organization `default`. It names no identity provider and no version: only whether single sign-on is set up and required.'
description: 'Return what this OpenBot offers and how people sign in to it: the edition, the features the apps draw, how large an attached file may be, and the sign-in options. Anybody may read it, signed in or not, because the sign-in screen reads it first. Signed in, it is answered in an organization the caller is a member of, and an organization they are not in, the organization `default` included, answers exactly as one that does not exist. Nobody signed in reads it in the organization `default`. It names no identity provider and no build: only whether single sign-on is set up and required, and which API versions and which releases of each OpenBot app it serves. It is never refused for the app''s version, so an app reads it first to learn whether it, or the OpenBot, needs an update.'
x-openbot-singleton: true
security:
- {}
Expand Down Expand Up @@ -22292,6 +22294,26 @@ components:
description: 'Whether this OpenBot has computers for Bots at all. False, a Bot has no computer, browser or sign-in to a website, and the computers answer 503 to every call. Not isolatedBots: an OpenBot whose Bots share one computer has computers (true) and cannot give a Bot one of its own (isolatedBots false).'
attachmentLimits:
$ref: '#/components/schemas/AttachmentLimits'
api:
type: array
description: 'The API versions this OpenBot serves, by major, such as v2. An app that speaks none of them can''t use it: when they are all newer than the app''s, the app needs an update; when they are all older, this OpenBot does. Absent from a release before it was published, which serves v2.'
minItems: 1
items:
type: string
pattern: ^v[1-9][0-9]{0,3}$
minimumClients:
$ref: '#/components/schemas/MinimumClients'
securityMinimumClients:
$ref: '#/components/schemas/MinimumClients'
description: 'The part of minimumClients raised because of a security problem in older releases: for each app named, the minimum is there for security. Absent or empty when none is.'
launcherApi:
type: integer
minimum: 1
description: The version of what OpenBot Desktop supplies when it starts this OpenBot on its own computer. It changes when Desktop must supply something new.
extensionApi:
type: integer
minimum: 1
description: The version of what the OpenBot Recorder and this OpenBot exchange.
AllowlistEntry:
type: string
minLength: 1
Expand Down Expand Up @@ -23467,6 +23489,20 @@ components:
description: 'What is wrong, item by item, when a refusal has more than one reason: each entry names the item and says what is wrong with it.'
items:
type: object
client:
type: string
x-extensible-enum:
- web
- desktop
- mobile
- recorder
description: On CLIENT_UPDATE_REQUIRED, the app the OpenBot-Client header named that is older than this OpenBot serves. A later OpenBot may name another app; read one you don't know as other.
minimumVersion:
type: string
description: On CLIENT_UPDATE_REQUIRED, the oldest release of that app this OpenBot serves.
security:
type: boolean
description: On CLIENT_UPDATE_REQUIRED, true when the minimum the app is below was raised because of a security problem in older releases.
ConversationJoinToken:
type: object
description: 'What a client needs to watch a conversation live: a token, and the socket and topic to use it on (the threadStream channel of api/asyncapi.yaml).'
Expand Down Expand Up @@ -23835,6 +23871,24 @@ components:
type: integer
minimum: 1
description: The largest text file, or a file of any other kind.
ClientRelease:
type: string
description: An OpenBot release, such as 1.1.0.
pattern: ^\d{1,6}\.\d{1,6}\.\d{1,6}(-[0-9A-Za-z.-]{1,64})?$
examples:
- 1.1.0
MinimumClients:
type: object
description: The oldest release of each OpenBot app this OpenBot serves. An app names itself in the OpenBot-Client header, and one older than its minimum here is refused with CLIENT_UPDATE_REQUIRED, everywhere but this deployment answer. An app not listed has no minimum. An OpenBot serves every app released in the last 12 months, so it names one only where its administrator raised it. Absent from a release before it was published.
properties:
web:
$ref: '#/components/schemas/ClientRelease'
desktop:
$ref: '#/components/schemas/ClientRelease'
mobile:
$ref: '#/components/schemas/ClientRelease'
recorder:
$ref: '#/components/schemas/ClientRelease'
ConversationWork:
type: object
description: 'Something still owed an answer in a conversation: another Bot that was asked and has not answered (handoff), or a routine running into it (routine).'
Expand Down Expand Up @@ -37111,6 +37165,33 @@ components:
retryable: true
requestId: req_example
traceId: trace_example
clientUpdateRequired:
value:
type: https://open.bot/errors/client-update-required
title: This app is too old for this OpenBot.
status: 400
detail: This OpenBot needs OpenBot Desktop 1.2.0 or later. Update OpenBot, then try again.
code: CLIENT_UPDATE_REQUIRED
category: validation
retryable: false
requestId: req_example
traceId: trace_example
client: desktop
minimumVersion: 1.2.0
clientUpdateRequiredSecurity:
value:
type: https://open.bot/errors/client-update-required
title: This app is too old for this OpenBot.
status: 400
detail: This version of OpenBot has a security problem. Update to keep using it.
code: CLIENT_UPDATE_REQUIRED
category: validation
retryable: false
requestId: req_example
traceId: trace_example
client: desktop
minimumVersion: 1.2.0
security: true
ConversationNotFound:
description: The conversation does not exist, was removed, or the caller is not in it, or the organization does not exist.
content:
Expand Down Expand Up @@ -41899,6 +41980,12 @@ components:
imageBytes: 104857600
documentBytes: 104857600
fileBytes: 104857600
api:
- v2
minimumClients:
desktop: 1.2.0
launcherApi: 1
extensionApi: 1
OrganizationSettingsExample:
summary: The settings, with what an administrator needs beside them.
value:
Expand Down
67 changes: 65 additions & 2 deletions api/openapi/admin-settings.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,11 @@ paths:
member of, and an organization they are not in, the organization
`default` included, answers exactly as one that does not exist. Nobody
signed in reads it in the organization `default`. It names no identity
provider and no version: only whether
single sign-on is set up and required.
provider and no build: only whether
single sign-on is set up and required, and which API versions and
which releases of each OpenBot app it serves. It is never refused for
the app's version, so an app reads it first to learn whether it, or
the OpenBot, needs an update.
x-openbot-singleton: true
security:
- {}
Expand Down Expand Up @@ -1086,6 +1089,61 @@ components:
a Bot one of its own (isolatedBots false).
attachmentLimits:
$ref: '#/components/schemas/AttachmentLimits'
api:
type: array
description: >-
The API versions this OpenBot serves, by major, such as v2. An app
that speaks none of them can't use it: when they are all newer than
the app's, the app needs an update; when they are all older, this
OpenBot does. Absent from a release before it was published, which
serves v2.
minItems: 1
items:
type: string
pattern: ^v[1-9][0-9]{0,3}$
minimumClients:
$ref: '#/components/schemas/MinimumClients'
securityMinimumClients:
$ref: '#/components/schemas/MinimumClients'
description: >-
The part of minimumClients raised because of a security problem in
older releases: for each app named, the minimum is there for
security. Absent or empty when none is.
launcherApi:
type: integer
minimum: 1
description: >-
The version of what OpenBot Desktop supplies when it starts this
OpenBot on its own computer. It changes when Desktop must supply
something new.
extensionApi:
type: integer
minimum: 1
description: The version of what the OpenBot Recorder and this OpenBot exchange.
MinimumClients:
type: object
description: >-
The oldest release of each OpenBot app this OpenBot serves. An app
names itself in the OpenBot-Client header, and one older than its
minimum here is refused with CLIENT_UPDATE_REQUIRED, everywhere but
this deployment answer. An app not listed has no minimum. An OpenBot
serves every app released in the last 12 months, so it names one only
where its administrator raised it. Absent from a release before it was
published.
properties:
web:
$ref: '#/components/schemas/ClientRelease'
desktop:
$ref: '#/components/schemas/ClientRelease'
mobile:
$ref: '#/components/schemas/ClientRelease'
recorder:
$ref: '#/components/schemas/ClientRelease'
ClientRelease:
type: string
description: An OpenBot release, such as 1.1.0.
pattern: ^\d{1,6}\.\d{1,6}\.\d{1,6}(-[0-9A-Za-z.-]{1,64})?$
examples: [1.1.0]
AttachmentLimits:
type: object
description: >-
Expand Down Expand Up @@ -2179,6 +2237,11 @@ components:
imageBytes: 104857600
documentBytes: 104857600
fileBytes: 104857600
api: [v2]
minimumClients:
desktop: 1.2.0
launcherApi: 1
extensionApi: 1
OrganizationSettingsExample:
summary: The settings, with what an administrator needs beside them.
value:
Expand Down
58 changes: 58 additions & 0 deletions api/openapi/common.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,22 @@ info:
SIGN_IN_UNAVAILABLE.


OpenBot's own apps name themselves on every request in the header
`OpenBot-Client`: `<kind>/<version>`, where kind is web, desktop,
mobile or recorder, such as `OpenBot-Client: desktop/1.1.0`. A header
may name more than one, separated by spaces: OpenBot Desktop adds its
own to the one its window's page sent. getDeployment says which API
versions this OpenBot serves and the oldest release of each app it
serves (minimumClients). Every other operation under /api/v2 refuses
an app older than that with 400 and the code CLIENT_UPDATE_REQUIRED, whose problem
names the app (client) and its minimum (minimumVersion) and whose
detail tells the person to update OpenBot. When that minimum was raised
because of a security problem in older releases, the problem also says
security: true, and getDeployment lists it under securityMinimumClients.
A program of your own need not send the header; without it nothing is
refused for a version.


This file is the single source of truth: the clients, the server's types,
the docs and the contract tests are all generated from it or checked
against it. A change that breaks an existing client fails the pull request.
Expand Down Expand Up @@ -993,6 +1009,21 @@ components:
reason: each entry names the item and says what is wrong with it.
items:
type: object
client:
type: string
x-extensible-enum: [web, desktop, mobile, recorder]
description: >-
On CLIENT_UPDATE_REQUIRED, the app the OpenBot-Client header named
that is older than this OpenBot serves. A later OpenBot may name
another app; read one you don't know as other.
minimumVersion:
type: string
description: On CLIENT_UPDATE_REQUIRED, the oldest release of that app this OpenBot serves.
security:
type: boolean
description: >-
On CLIENT_UPDATE_REQUIRED, true when the minimum the app is below
was raised because of a security problem in older releases.
ConversationJoinToken: { $ref: './conversations.yaml#/components/schemas/ConversationJoinToken' }
CredentialKind: { $ref: './model-connections.yaml#/components/schemas/CredentialKind' }
Credential: { $ref: './model-connections.yaml#/components/schemas/Credential' }
Expand Down Expand Up @@ -1310,6 +1341,33 @@ components:
retryable: true
requestId: req_example
traceId: trace_example
clientUpdateRequired:
value:
type: https://open.bot/errors/client-update-required
title: This app is too old for this OpenBot.
status: 400
detail: This OpenBot needs OpenBot Desktop 1.2.0 or later. Update OpenBot, then try again.
code: CLIENT_UPDATE_REQUIRED
category: validation
retryable: false
requestId: req_example
traceId: trace_example
client: desktop
minimumVersion: 1.2.0
clientUpdateRequiredSecurity:
value:
type: https://open.bot/errors/client-update-required
title: This app is too old for this OpenBot.
status: 400
detail: This version of OpenBot has a security problem. Update to keep using it.
code: CLIENT_UPDATE_REQUIRED
category: validation
retryable: false
requestId: req_example
traceId: trace_example
client: desktop
minimumVersion: 1.2.0
security: true
ConversationNotFound:
description: >-
The conversation does not exist, was removed, or the caller is not in
Expand Down
Loading
Loading