Docs
API 1.39
Status
Programs

Replace a draft version's definition in place; published versions are immutable

PUT /v1/programs/{id}/versions/{n}: Replace a draft version's definition in place; published versions are immutable

PUT /v1/programs/{id}/versions/{n}
Operation idupdateProgramVersion
Key scoperun: keys that run jobs (and admin keys)
SectionPrograms

#Parameters

NameInTypeRequiredDescription
idpathstringyesmin length 1
npathintegeryes≥ 1

#Request body

FieldTypeRequiredDescription
definitionProgramDefinitionyes
notesstringmax length 1000
draft_idstringThe builder draft this version was built from; its picker confirmations move to it. · pattern ^dft_[0-9a-hjkmnp-tv-z]{26}$

#Example request

curl -X PUT "https://api.kaab.ist/v1/programs/{id}/versions/{n}" \
  -H "Authorization: Bearer $KAAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

#Responses

#200

Version

ProgramVersion

{
  "id": "pv_01j9zqk3q7m4n5p6r7s8t9v0wx",
  "object": "program_version",
  "program_id": "prg_01j9zqk3q7m4n5p6r7s8t9v0wx",
  "version": 3,
  "status": "published",
  "definition": {
    "kaab": "1",
    "steps": [
      {
        "goto": "https://shop.example.com/p/1"
      },
      {
        "extract": {
          "title": "h1"
        }
      }
    ]
  },
  "definition_hash": "sha256:9ab1",
  "lint": {
    "errors": [],
    "warnings": [
      {
        "code": "W001",
        "path": "steps[0]",
        "message": "`goto` without `expect`"
      }
    ]
  },
  "notes": "healing: relocate price",
  "source": "proposal",
  "created_at": "2026-09-18T10:00:00Z",
  "published_at": "2026-09-18T10:00:00Z"
}

#Errors

Every error answers with the error envelope; its code is one of the error codes.

StatusWhen
400request_invalid: request validation failed
401Missing or invalid API key
402insufficient_credits: top up to continue
403The key's scope does not cover this operation
404Resource not found
409Conflicting state (see error.code)
422Semantically invalid request (see error.code)
429Rate limited; see Retry-After
500internal: unexpected server error

Was this page helpful?