Skip to content
Updawg

Ask every host a proposal targets whether it can take the change (DAWG-153).

POST
/v1/orgs/{org}/proposals/{proposal_id}/preflight
curl --request POST \
  --url https://api.updawg.net/v1/orgs/example/proposals/example/preflight

Each is sent a signed run_preflight job naming exactly the proposal’s packages. The agent changes nothing: it looks at disk space, held packages, edited configuration files, DKMS modules, snapshots and reboots, and answers pass, warn or fail for each. For a proposal that has not started changing hosts (open, snoozed, scheduled) or has halted. Asking again replaces the last results once they are all in.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
org
required
string

Organization slug.

proposal_id
required
string

The prp_… id.

Responses

Section titled “Responses”

202

Section titled “202”

Asked for; the jobs are being signed.

Media typeapplication/json

A proposal’s preflight.

object
blocked

Why one cannot be asked for now. Absent when it can.

string | null
hosts
required

Every host the proposal targets that is still in the fleet.

Array<object>
object
checks
required

What the host found, once it has reported. A failing check is an answer, not a failed job.

Array<object>
object
items
required

The specifics: a package, a file, a module.

Array<string>
name
required

Stable, for code: disk_space, held_packages, modified_conffiles, dkms_modules, snapshot, reboot, for a package change approved_only, and for a release upgrade release_upgrade and third_party_repos. A newer agent may add more.

string
status
required

pass, warn or fail.

string
summary
required

One sentence for a person, saying what to do when it is not a pass.

string
finished_at
string | null format: date-time
host_id
required
string
hostname
required
string
job_status

The current preflight job’s status: queued, delivered, running, succeeded, failed, rejected_by_host, expired, cancelled. Absent before one is signed for this host.

string | null
problem

Why there are no checks: the host refused the job (an agent not permitted preflight says so), or it failed.

string | null
requested
One of:

Who asked last, and when. Absent until somebody does.

object
at
required
string format: date-time
by
required

The usr_… id.

string
email
required
string
name
string | null
Examplegenerated
{
  "blocked": "example",
  "hosts": [
    {
      "checks": [
        {
          "items": [
            "example"
          ],
          "name": "example",
          "status": "example",
          "summary": "example"
        }
      ],
      "finished_at": "2026-04-15T12:00:00Z",
      "host_id": "example",
      "hostname": "example",
      "job_status": "example",
      "problem": "example"
    }
  ],
  "requested": {
    "at": "2026-04-15T12:00:00Z",
    "by": "example",
    "email": "example",
    "name": "example"
  }
}

401

Section titled “401”

No session.

Media typeapplication/json
object
detail
string | null
status
required
integer format: int32
title
required
string
type
required
string
Examplegenerated
{
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

403

Section titled “403”

Not permitted for this role.

Media typeapplication/json
object
detail
string | null
status
required
integer format: int32
title
required
string
type
required
string
Examplegenerated
{
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

404

Section titled “404”

No such proposal here.

Media typeapplication/json
object
detail
string | null
status
required
integer format: int32
title
required
string
type
required
string
Examplegenerated
{
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

409

Section titled “409”

Not possible now; detail says why.

Media typeapplication/json
object
detail
string | null
status
required
integer format: int32
title
required
string
type
required
string
Examplegenerated
{
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}

429

Section titled “429”

Over the organization’s request limit. Retry-After says when to try again; RateLimit-Limit is the burst.

Media typeapplication/json
object
detail
string | null
status
required
integer format: int32
title
required
string
type
required
string
Examplegenerated
{
  "detail": "example",
  "status": 1,
  "title": "example",
  "type": "example"
}