Nebraska is the update management server for Flatcar Container Linux. It exposes a REST API for managing update applications, packages, channels, groups, instances, and activity. Flatcar instances poll Nebraska using the Omaha protocol for controlled rollouts, version pinning, and update monitoring across fleets of Flatcar nodes.
openapi: "3.0.0"
info:
version: 0.0.1
title: Nebraska
description: Nebraska is an update manager.
contact:
name: Flatcar Container Linux
email: [email protected]
url: http://flatcar.org
paths:
/login/cb:
get:
operationId: loginCb
description: GitHub OAuth callback (GitHub mode only)
security: []
responses:
"200":
description: OAuth callback processed successfully
"302":
description: Redirect to originally requested URL
"400":
description: Bad request
"401":
description: Unauthorized
"500":
description: Internal server error
"501":
description: Not implemented for OIDC auth mode
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/login/validate_token:
get:
operationId: validateToken
description: validate JWT access token (OIDC mode only)
security: []
responses:
"200":
description: validate token response
"401":
description: invalid or expired token
"501":
description: Not implemented for GitHub auth mode
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/login/webhook:
post:
operationId: loginWebhook
description: GitHub webhook (GitHub mode only)
security: []
parameters:
- in: header
name: X-Hub-Signature
required: true
schema:
type: string
- in: header
name: X-Github-Event
required: true
schema:
type: string
responses:
"200":
description: login webhook response
"501":
description: Not implemented for OIDC auth mode
content:
application/json:
schema:
$ref: "#/components/schemas/errorResponse"
/health:
get:
operationId: health
description: health endpoint
security: []
responses:
"200":
description: health response
/config:
get:
operationId: getConfig
description: get app config
security: []
responses:
"200":
description: get config response
content:
application/json:
schema:
$ref: "#/components/schemas/config"
/v1/update:
post:
operationId: omaha
description: omaha endpoint
security: []
requestBody:
description: payload for omaha endpoint
required: true
content:
text/xml:
schema:
$ref: "#/components/schemas/omahaRequest"
responses:
"200":
description: Omaha Response
"400":
description: Bad Request if request size is too large
/api/apps:
get:
description: get Apps
operationId: paginateApps
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: query
name: page
required: false
schema:
type: integer
minimum: 0
- in: query
name: perpage
required: false
schema:
type: integer
minimum: 10
responses:
"200":
description: Get App success response
content:
application/json:
schema:
$ref: "#/components/schemas/appsPage"
"404":
description: Apps not found response
"400":
description: Bad request response
post:
description: create app
operationId: createApp
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: query
name: clone_from
required: false
schema:
type: string
requestBody:
description: payload for create app
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/appConfig"
responses:
"200":
description: Create App success response
content:
application/json:
schema:
$ref: "#/components/schemas/application"
"400":
description: Bad request response
"500":
description: Create App error response
/api/apps/{appIDorProductID}:
get:
description: get app
operationId: getApp
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
responses:
"200":
description: Get app success response
content:
application/json:
schema:
$ref: "#/components/schemas/application"
"404":
description: App not found response
"500":
description: Get App error response
put:
description: update app
operationId: updateApp
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
requestBody:
description: payload for update app
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/appConfig"
responses:
"200":
description: Update App success response
content:
application/json:
schema:
$ref: "#/components/schemas/application"
"400":
description: Bad request response
"500":
description: Update app error response
delete:
description: delete app
operationId: deleteApp
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
responses:
"200":
description: Delete App success response
"500":
description: Delete App error response
/api/apps/{appIDorProductID}/groups:
get:
description: paginate groups of an app
operationId: paginateGroups
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: query
name: page
required: false
schema:
type: integer
minimum: 0
- in: query
name: perpage
required: false
schema:
type: integer
minimum: 10
responses:
"200":
description: get Groups success response
content:
application/json:
schema:
$ref: "#/components/schemas/groupPage"
"404":
description: Groups not found response
"500":
description: get Groups error response
post:
description: create group in app
operationId: createGroup
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
requestBody:
description: payload for create group
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/groupConfig"
responses:
"200":
description: Create Group success response
content:
application/json:
schema:
$ref: "#/components/schemas/group"
"400":
description: Bad request response
"500":
description: Create Group error response
/api/apps/{appIDorProductID}/groups/{groupID}:
get:
description: get group given its groupID and appID
operationId: getGroup
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
responses:
"200":
description: Get Group success response
content:
application/json:
schema:
$ref: "#/components/schemas/group"
"404":
description: Group not found response
"500":
description: Get Group error response
put:
description: update group given its groupID and appID
operationId: updateGroup
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
requestBody:
description: payload for update group
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/groupConfig"
responses:
"200":
description: Update Group success response
content:
application/json:
schema:
$ref: "#/components/schemas/group"
"404":
description: Group not found response
"400":
description: Update Group Bad request response
"500":
description: Update Group error response
delete:
description: delete group given its groupID and appID
operationId: deleteGroup
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
responses:
"200":
description: Delete Group success response
"404":
description: Group not found response
"500":
description: Delete Group error response
/api/apps/{appIDorProductID}/groups/{groupID}/version_timeline:
get:
description: get version timeline of a group given its groupID and appID
operationId: getGroupVersionTimeline
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
- in: query
name: duration
required: true
schema:
type: string
responses:
"200":
description: Version Timeline of group success response
content:
application/json:
schema:
$ref: "#/components/schemas/groupVersionCountTimeline"
"404":
description: Group not found response
"500":
description: Version Timeline of group error response
/api/apps/{appIDorProductID}/groups/{groupID}/status_timeline:
get:
description: get status timeline of a group given its groupID and appID
operationId: getGroupStatusTimeline
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
- in: query
name: duration
required: true
schema:
type: string
responses:
"200":
description: Status Timeline of group success response
content:
application/json:
schema:
$ref: "#/components/schemas/groupStatusCountTimeline"
"404":
description: Group not found response
"500":
description: Status Timeline of group error response
/api/apps/{appIDorProductID}/groups/{groupID}/instances_stats:
get:
description: get instance stats of a group given its groupID and appID
operationId: getGroupInstanceStats
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
- in: query
name: duration
required: true
schema:
type: string
responses:
"200":
description: Instance Stats of group success response
content:
application/json:
schema:
$ref: "#/components/schemas/groupInstanceStats"
"404":
description: Group not found response
"500":
description: Instance Stats of group error response
/api/apps/{appIDorProductID}/groups/{groupID}/version_breakdown:
get:
description: get version breakdown of a group given its groupID and appID
operationId: getGroupVersionBreakdown
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
responses:
"200":
description: Version Breakdown of group success response
content:
application/json:
schema:
$ref: "#/components/schemas/groupVersionBreakdown"
"404":
description: Group not found response
"500":
description: Version Breakdown of group error response
/api/apps/{appIDorProductID}/channels:
get:
description: paginate channels of an app
operationId: paginateChannels
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in : path
name: appIDorProductID
required: true
schema:
type: string
- in: query
name: page
required: false
schema:
type: integer
minimum: 0
- in: query
name: perpage
required: false
schema:
type: integer
minimum: 10
responses:
"200":
description: Get channels success response
content:
application/json:
schema:
$ref: "#/components/schemas/channelPage"
"404":
description: Channel not found response
"500":
description: Get channels error response
post:
description: create channel
operationId: createChannel
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in : path
name: appIDorProductID
required: true
schema:
type: string
requestBody:
description: payload for create channel
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/channelConfig"
responses:
"200":
description: Create channel success response
content:
application/json:
schema:
$ref: "#/components/schemas/channel"
"400":
description: Bad request response
"500":
description: Create channel error response
/api/apps/{appIDorProductID}/channels/{channelID}:
get:
description: get channel by id
operationId: getChannel
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: channelID
required: true
schema:
type: string
responses:
"200":
description: Get channel success response
content:
application/json:
schema:
$ref: "#/components/schemas/channel"
"404":
description: Channel not found response
"500":
description: Get channel error response
put:
description: update channel by id
operationId: updateChannel
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: channelID
required: true
schema:
type: string
requestBody:
description: payload for create channel
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/channelConfig"
responses:
"200":
description: Update channel success response
content:
application/json:
schema:
$ref: "#/components/schemas/channel"
"404":
description: Channel not found response
"400":
description: Bad request response
"500":
description: Update channel error response
delete:
description: delete channel by id
operationId: deleteChannel
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: channelID
required: true
schema:
type: string
responses:
"200":
description: Delete channel success response
"500":
description: Delete channel error response
/api/channels/{channelID}/floors:
get:
description: paginate floor packages of a channel
operationId: paginateChannelFloors
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: channelID
required: true
schema:
type: string
- in: query
name: page
schema:
type: integer
required: false
- in: query
name: perpage
schema:
type: integer
required: false
responses:
"200":
description: Paginate channel floors success response
content:
application/json:
schema:
type: object
required:
- packages
- current_page
- last_page
- total_count
properties:
packages:
type: array
items:
$ref: "#/components/schemas/package"
current_page:
type: integer
format: int32
last_page:
type: integer
format: int32
total_count:
type: integer
format: int32
"500":
description: Get channel floors error response
/api/channels/{channelID}/floors/{packageID}:
put:
description: Create or update a floor package relationship (idempotent operation)
operationId: setChannelFloor
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: channelID
required: true
schema:
type: string
- in: path
name: packageID
required: true
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
floor_reason:
type: string
nullable: true
description: Optional reason for marking this package as a floor (e.g., "Introduces needed filesystem support to handle new updates after this version")
maxLength: 500
example: "Introduces btrfs support in update-engine to handle new updates after this version"
responses:
"200":
description: Floor package relationship created or updated successfully
"400":
description: Invalid request (architecture mismatch, wrong application, etc.)
"404":
description: Channel or package not found
"500":
description: Set channel floor error response
delete:
description: remove package as floor for a channel
operationId: removeChannelFloor
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: channelID
required: true
schema:
type: string
- in: path
name: packageID
required: true
schema:
type: string
responses:
"200":
description: Remove channel floor success response
"404":
description: Floor relationship not found
"500":
description: Remove channel floor error response
/api/apps/{appIDorProductID}/packages:
get:
description: paginate packages of an app
operationId: paginatePackages
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: query
name: page
required: false
schema:
type: integer
minimum: 0
- in: query
name: perpage
required: false
schema:
type: integer
minimum: 10
- in: query
name: searchVersion
schema:
type: string
responses:
"200":
description: get Packages success response
content:
application/json:
schema:
$ref: "#/components/schemas/packagePage"
"404":
description: Packages not found response
post:
description: create package
operationId: createPackage
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
requestBody:
description: payload for create package
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/packageConfig"
responses:
"200":
description: Create Package success response
content:
application/json:
schema:
$ref: "#/components/schemas/package"
"400":
description: Create Package bad request response
"500":
description: Create package error response
/api/apps/{appIDorProductID}/packages/{packageID}:
get:
description: get package given its packageID and appID
operationId: getPackage
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: packageID
required: true
schema:
type: string
responses:
"200":
description: Get Package success response
content:
application/json:
schema:
$ref: "#/components/schemas/package"
"404":
description: Package not found response
"500":
description: Get Package error response
put:
description: update package given its packageID and appID
operationId: updatePackage
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: packageID
required: true
schema:
type: string
requestBody:
description: payload for update package
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/packageConfig"
responses:
"200":
description: Update Package success response
content:
application/json:
schema:
$ref: "#/components/schemas/package"
"404":
description: Package not found response
"500":
description: Update package error response
delete:
description: delete package given its packageID and appID
operationId: deletePackage
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: packageID
required: true
schema:
type: string
responses:
"200":
description: Delete Package success response
"404":
description: Package not found response
"500":
description: Delete package error response
/api/apps/{appIDorProductID}/packages/{packageID}/floor-channels:
get:
description: get all channels where a package is marked as a floor
operationId: getPackageFloorChannels
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: packageID
required: true
schema:
type: string
responses:
"200":
description: Get Package Floor Channels success response
content:
application/json:
schema:
type: object
properties:
channels:
type: array
items:
type: object
properties:
channel:
$ref: "#/components/schemas/channel"
floor_reason:
type: string
nullable: true
count:
type: integer
"404":
description: Package not found
"500":
description: Internal server error
/api/apps/{appIDorProductID}/groups/{groupID}/instances:
get:
description: get instances of a group given its groupID and appID
operationId: getGroupInstances
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
- in: query
name: status
required: true
schema:
type: integer
- in: query
name: page
required: false
schema:
type: integer
minimum: 0
- in: query
name: perpage
required: false
schema:
type: integer
minimum: 10
- in: query
name: sortFilter
required: false
schema:
type: string
- in: query
name: sortOrder
required: false
schema:
type: string
- in: query
name: searchFilter
required: false
schema:
type: string
- in: query
name: searchValue
required: false
schema:
type: string
- in: query
name: duration
required: true
schema:
type: string
- in: query
name: version
required: false
schema:
type: string
responses:
"200":
description: Get Instances of a Group success response
content:
application/json:
schema:
$ref: "#/components/schemas/instancePage"
"500":
description: Get Instances of a Group error response
/api/apps/{appIDorProductID}/groups/{groupID}/instancescount:
get:
description: get instance count of a group given its groupID and appID
operationId: getGroupInstancesCount
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
- in: query
name: duration
required: true
schema:
type: string
responses:
"200":
description: Get Instance count of a Group success response
content:
application/json:
schema:
$ref: "#/components/schemas/instanceCount"
"500":
description: Get Instance count of a Group error response
/api/apps/{appIDorProductID}/groups/{groupID}/instances/{instanceID}:
get:
description: get instance of a group given its groupID and appID
operationId: getInstance
security:
- oidcBearerAuth: []
- oidcCookieAuth: []
- githubCookieAuth: []
parameters:
- in: path
name: appIDorProductID
required: true
schema:
type: string
- in: path
name: groupID
required: true
schema:
type: string
- in: path
name: instanceID
required: true
schema:
type: string
responses:
"200":
description: Get instance success response
content:
application/json:
schema:
$ref: "#/components/schemas/instance"
"404":
description: Instance not found response
"500":
description: Get instance error response
/api/apps/{appIDorPro
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flatcar-container-linux/refs/heads/main/openapi/nebraska-update-api-openapi.yml