Procedure executions service<a class="headerlink" href="#procedure-executions-service" title="Link to this heading">#

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

Fields of ProcedureExecutionState

globalFields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

assetRid

assetRid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

stringValue

stringValue string

doubleValue

doubleValue number

booleanValue

booleanValue boolean

intValue

intValue string (int64)

stringsValue

stringsValue Strings

Fields of Strings

values array of string

ingestJobRid

ingestJobRid string

runRid

runRid string

fileUploadValue

fileUploadValue FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUploadValue

multiFileUploadValue MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
templateNodeId string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
templateCommitId string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

templateNodeId string

Unique identifier of the template node this execution node is based on. At least 1 character.

isOutdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

notStarted

notStarted ExecutionStepNotStarted

inProgress

inProgress ExecutionStepInProgress

Fields of ExecutionStepInProgress

startedAt string (date-time)
startedBy string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skippedAt string (date-time)
skippedBy string
skipReason string
startedAt string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
startedBy string
submittedAt string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submittedBy string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string
succeededAt string (date-time)
succeededBy string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

startedAt string (date-time): Optional because a step can reach ERRORED without having been started
startedBy string
submittedAt string (date-time): Optional because a step can be errored before being submitted
submittedBy string
erroredAt string (date-time)
erroredBy string
error string
skippedAt string (date-time): Optional because a step could be skipped but then error while running completion actions
skippedBy string
skipReason string
succeededAt string (date-time): Optional because a step can succeed but then error while running completion actions
succeededBy string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

curl

curl -X POST "https://api.gov.nominal.io/api/procedures/v1/executions/procedures/<procedure rid>" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "procedureCommitId": "<procedure commit id>",
  "title": "<title>",
  "description": "<description>",
  "startImmediately": true
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/procedures/v1/executions/procedures/<procedure rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "procedureCommitId": "<procedure commit id>",
        "title": "<title>",
        "description": "<description>",
        "startImmediately": True,
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/procedures/v1/executions/procedures/<procedure rid>",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "procedureCommitId": "<procedure commit id>",
        "title": "<title>",
        "description": "<description>",
        "startImmediately": True,
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/procedures/v1/executions/procedures/<procedure rid>",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "procedureCommitId": "<procedure commit id>",
                "title": "<title>",
                "description": "<description>",
                "startImmediately": True,
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedureRid": "<procedure rid>",
      "procedureCommitId": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedBy": "<updated by>",
      "updatedAt": "2026-01-01T00:00:00Z",
      "startedAt": "2026-01-01T00:00:00Z",
      "startedBy": "<started by>",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finishedBy": "<finished by>",
      "abortedAt": "2026-01-01T00:00:00Z",
      "abortedBy": "<aborted by>",
      "failedAt": "2026-01-01T00:00:00Z",
      "failedBy": "<failed by>",
      "failedReason": "<failed reason>",
      "assetRids": [
        "<asset rids>"
      ],
      "isArchived": true
    },
    "state": {
      "globalFields": {
        "<key>": {
          "assetRid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "templateNodeId": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "templateCommitId": "<template commit id>"
          }
        }
      },
      "sectionEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      },
      "stepEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Search procedure executions#

GET /procedures/v1/executions/search

Search for procedure executions. The JSON transcoder ranks literal path segments above /{...} template captures, so the literal /search route wins over the /{procedure_execution_rid} template regardless of declaration order.

Query parameters

query.searchText string
query.label string
query.property.name string
query.property.value string
query.workspace string
query.procedureRid string
query.commitId string
query.createdBy string
query.progressStatus string, one of PROCEDURE_EXECUTION_PROGRESS_STATUS_UNSPECIFIED, PROCEDURE_EXECUTION_PROGRESS_STATUS_NOT_STARTED, PROCEDURE_EXECUTION_PROGRESS_STATUS_IN_PROGRESS, PROCEDURE_EXECUTION_PROGRESS_STATUS_FINISHED, PROCEDURE_EXECUTION_PROGRESS_STATUS_ABORTED
query.assetsFilter.assetRids array of string
query.assetsFilter.operator string, one of OPERATOR_UNSPECIFIED, OPERATOR_OR, OPERATOR_AND
query.isArchived boolean
sortOptions.isDescending boolean: Defaults to descending
sortOptions.sortField string, one of SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_UNSPECIFIED, SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT, SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_STARTED_AT, SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_FINISHED_AT, SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_UPDATED_AT required
pageSize integer: Page sizes greater than 1_000 will be rejected. Default pageSize is 100. From 1 to 1,000.
nextPageToken string

Response

procedureExecutions array of ProcedureExecutionMetadata

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

nextPageToken string

Request

curl

curl "https://api.gov.nominal.io/api/procedures/v1/executions/search?sortOptions.sortField=SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/procedures/v1/executions/search?sortOptions.sortField=SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/procedures/v1/executions/search?sortOptions.sortField=SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/procedures/v1/executions/search?sortOptions.sortField=SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecutions": [
    {
      "rid": "<rid>",
      "procedureRid": "<procedure rid>",
      "procedureCommitId": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedBy": "<updated by>",
      "updatedAt": "2026-01-01T00:00:00Z",
      "startedAt": "2026-01-01T00:00:00Z",
      "startedBy": "<started by>",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finishedBy": "<finished by>",
      "abortedAt": "2026-01-01T00:00:00Z",
      "abortedBy": "<aborted by>",
      "failedAt": "2026-01-01T00:00:00Z",
      "failedBy": "<failed by>",
      "failedReason": "<failed reason>",
      "assetRids": [
        "<asset rids>"
      ],
      "isArchived": true
    }
  ],
  "nextPageToken": "<next page token>"
}

Batch unarchive procedure executions#

POST /procedures/v1/executions/unarchive

Unarchive procedure executions

Body

procedureExecutionRids array of string

Response

procedureExecutionRids array of string

Request

curl

curl -X POST "https://api.gov.nominal.io/api/procedures/v1/executions/unarchive" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "procedureExecutionRids": [
    "<procedure execution rids>"
  ]
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/procedures/v1/executions/unarchive",
    headers={"Authorization": "Bearer <api key>"},
    json={"procedureExecutionRids": ["<procedure execution rids>"]},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/procedures/v1/executions/unarchive",
    headers={"Authorization": "Bearer <api key>"},
    json={"procedureExecutionRids": ["<procedure execution rids>"]},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/procedures/v1/executions/unarchive",
            headers={"Authorization": "Bearer <api key>"},
            json={"procedureExecutionRids": ["<procedure execution rids>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecutionRids": [
    "<procedure execution rids>"
  ]
}

Get procedure execution#

GET /procedures/v1/executions/{procedureExecutionRid}

Get a procedure execution by its RID

Path parameters

procedureExecutionRid string required

Query parameters

includeDisplayGraph boolean: If true, the display graph will be included in the response. Default is false.

Response

procedureExecution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

Fields of ProcedureExecutionState

globalFields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

assetRid

assetRid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

stringValue

stringValue string

doubleValue

doubleValue number

booleanValue

booleanValue boolean

intValue

intValue string (int64)

stringsValue

stringsValue Strings

Fields of Strings

values array of string

ingestJobRid

ingestJobRid string

runRid

runRid string

fileUploadValue

fileUploadValue FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUploadValue

multiFileUploadValue MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
templateNodeId string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
templateCommitId string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

templateNodeId string

Unique identifier of the template node this execution node is based on. At least 1 character.

isOutdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

notStarted

notStarted ExecutionStepNotStarted

inProgress

inProgress ExecutionStepInProgress

Fields of ExecutionStepInProgress

startedAt string (date-time)
startedBy string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skippedAt string (date-time)
skippedBy string
skipReason string
startedAt string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
startedBy string
submittedAt string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submittedBy string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string
succeededAt string (date-time)
succeededBy string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

startedAt string (date-time): Optional because a step can reach ERRORED without having been started
startedBy string
submittedAt string (date-time): Optional because a step can be errored before being submitted
submittedBy string
erroredAt string (date-time)
erroredBy string
error string
skippedAt string (date-time): Optional because a step could be skipped but then error while running completion actions
skippedBy string
skipReason string
succeededAt string (date-time): Optional because a step can succeed but then error while running completion actions
succeededBy string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

curl

curl "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedureRid": "<procedure rid>",
      "procedureCommitId": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedBy": "<updated by>",
      "updatedAt": "2026-01-01T00:00:00Z",
      "startedAt": "2026-01-01T00:00:00Z",
      "startedBy": "<started by>",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finishedBy": "<finished by>",
      "abortedAt": "2026-01-01T00:00:00Z",
      "abortedBy": "<aborted by>",
      "failedAt": "2026-01-01T00:00:00Z",
      "failedBy": "<failed by>",
      "failedReason": "<failed reason>",
      "assetRids": [
        "<asset rids>"
      ],
      "isArchived": true
    },
    "state": {
      "globalFields": {
        "<key>": {
          "assetRid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "templateNodeId": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "templateCommitId": "<template commit id>"
          }
        }
      },
      "sectionEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      },
      "stepEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      }
    }
  },
  "displayGraph": {
    "topLevelNodes": [
      "<top level nodes>"
    ],
    "sectionToSortedChildren": {
      "<key>": {
        "nodeIds": [
          "<node ids>"
        ]
      }
    }
  }
}

Update procedure execution metadata#

PUT /procedures/v1/executions/{procedureExecutionRid}/metadata

Update the metadata of a procedure execution

Path parameters

procedureExecutionRid string required

Body

title string

description string

commitId string

labels LabelUpdateWrapper

Fields of LabelUpdateWrapper

labels array of string

properties PropertyUpdateWrapper

Fields of PropertyUpdateWrapper

properties map of string to string

Response

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/metadata" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "title": "<title>",
  "description": "<description>",
  "commitId": "<commit id>",
  "labels": {
    "labels": [
      "<labels>"
    ]
  },
  "properties": {
    "properties": {
      "<key>": "<value>"
    }
  }
}'

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/metadata",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "title": "<title>",
        "description": "<description>",
        "commitId": "<commit id>",
        "labels": {"labels": ["<labels>"]},
        "properties": {"properties": {"<key>": "<value>"}},
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/metadata",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "title": "<title>",
        "description": "<description>",
        "commitId": "<commit id>",
        "labels": {"labels": ["<labels>"]},
        "properties": {"properties": {"<key>": "<value>"}},
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/metadata",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "title": "<title>",
                "description": "<description>",
                "commitId": "<commit id>",
                "labels": {"labels": ["<labels>"]},
                "properties": {"properties": {"<key>": "<value>"}},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "metadata": {
    "rid": "<rid>",
    "procedureRid": "<procedure rid>",
    "procedureCommitId": "<procedure commit id>",
    "title": "<title>",
    "description": "<description>",
    "labels": [
      "<labels>"
    ],
    "properties": {
      "<key>": "<value>"
    },
    "createdBy": "<created by>",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedBy": "<updated by>",
    "updatedAt": "2026-01-01T00:00:00Z",
    "startedAt": "2026-01-01T00:00:00Z",
    "startedBy": "<started by>",
    "finishedAt": "2026-01-01T00:00:00Z",
    "finishedBy": "<finished by>",
    "abortedAt": "2026-01-01T00:00:00Z",
    "abortedBy": "<aborted by>",
    "failedAt": "2026-01-01T00:00:00Z",
    "failedBy": "<failed by>",
    "failedReason": "<failed reason>",
    "assetRids": [
      "<asset rids>"
    ],
    "isArchived": true
  }
}

Update step channel capture status#

PUT /procedures/v1/executions/{procedureExecutionRid}/steps/{stepId}/channel-capture-status

Called by the backend (channel capture executor) to merge a single channel-capture status into a step’s channel_capture_statuses. Identity is (output_field_id, capture_moment); existing entries for that identity are replaced. Statuses are written incrementally as captures progress (in_progress -> terminal), so this RPC is expected to be called multiple times per capture.

Path parameters

procedureExecutionRid string required
stepId string required: The unique identifier of the execution step to update. At least 1 character.

Body

channelCaptureStatus ChannelCaptureStatus

The status to merge into the step’s channel_capture_statuses, identified by (output_field_id, capture_moment). Replaces any previously written entry with the same identity.

Fields of ChannelCaptureStatus

outputFieldId string

The output_field_id of the capture. Used together with capture_moment to identify which capture this status refers to. At least 1 character.

captureMoment CaptureMoment

Which step lifecycle moment this capture corresponds to. A given output_field_id may be captured at both step start and step completion, in which case there will be one ChannelCaptureStatus entry per moment. Must be a defined, non-UNSPECIFIED CaptureMoment — capture_moment is half of the identity key used for merging, so accepting the zero value would produce a bogus key.

Values of CaptureMoment

CAPTURE_MOMENT_UNSPECIFIED: Required zero-value enum sentinel. Do not include this in capture_moments.
CAPTURE_MOMENT_STEP_START
CAPTURE_MOMENT_STEP_COMPLETION

one of inProgress, succeeded, failed, skipped required

inProgress

inProgress ChannelCaptureInProgress

Fields of ChannelCaptureInProgress

startedAt string (date-time)

succeeded

succeeded ChannelCaptureSucceeded

Fields of ChannelCaptureSucceeded

startedAt string (date-time)

capturedAt string (date-time)

value CapturedValue required

Fields of CapturedValue

one of doubleValue, intValue, boolValue, stringValue required

doubleValue

doubleValue number

intValue

intValue string (int64)

boolValue

boolValue boolean

stringValue

stringValue string

failed

failed ChannelCaptureFailed

Fields of ChannelCaptureFailed

startedAt string (date-time)

failedAt string (date-time)

reason ChannelCaptureFailureReason

Values of ChannelCaptureFailureReason

CHANNEL_CAPTURE_FAILURE_REASON_UNSPECIFIED
CHANNEL_CAPTURE_FAILURE_REASON_DATA_SOURCE_NOT_FOUND: The channel’s data_source_ref could not be resolved to a concrete data source at execution time (e.g. the named ref is not present in the execution’s data scopes or run data sources).
CHANNEL_CAPTURE_FAILURE_REASON_CHANNEL_NOT_FOUND: The data source was resolved but the named channel (with the configured tags, if any) does not exist on it, or its metadata could not be fetched.
CHANNEL_CAPTURE_FAILURE_REASON_UNSUPPORTED_CHANNEL_TYPE: The channel’s data type cannot be represented by CapturedValue, or the channel’s data type is unset. Permanent for this channel — re-running will not help.
CHANNEL_CAPTURE_FAILURE_REASON_TIMEOUT_NO_DATA: No data point arrived within the capture timeout window (subscription opened but yielded no value before the deadline).
CHANNEL_CAPTURE_FAILURE_REASON_INTERNAL_ERROR: Catch-all for backend / infrastructure failures that prevented capture — e.g. websocket connect/subscribe/stream failure, missing websocket configuration, downstream event creation failure, interrupt, or any other unexpected failure. See error_message for the specific cause.

errorMessage string

Free-text detail. Must not contain unsafe content — same conventions as other user-visible error_message fields on procedure executions. Capped to bound payload size; truncate at the producer if a longer detail is available. At most 4,096 characters.

skipped

skipped ChannelCaptureSkipped

Fields of ChannelCaptureSkipped

skippedAt string (date-time)

reason ChannelCaptureSkipReason

Values of ChannelCaptureSkipReason

CHANNEL_CAPTURE_SKIP_REASON_UNSPECIFIED
CHANNEL_CAPTURE_SKIP_REASON_RUN_SCOPED_UNSUPPORTED: The capture targets a run-scoped channel locator, which is not yet supported.

Response

procedureExecution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

Fields of ProcedureExecutionState

globalFields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

assetRid

assetRid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

stringValue

stringValue string

doubleValue

doubleValue number

booleanValue

booleanValue boolean

intValue

intValue string (int64)

stringsValue

stringsValue Strings

Fields of Strings

values array of string

ingestJobRid

ingestJobRid string

runRid

runRid string

fileUploadValue

fileUploadValue FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUploadValue

multiFileUploadValue MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
templateNodeId string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
templateCommitId string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

templateNodeId string

Unique identifier of the template node this execution node is based on. At least 1 character.

isOutdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

notStarted

notStarted ExecutionStepNotStarted

inProgress

inProgress ExecutionStepInProgress

Fields of ExecutionStepInProgress

startedAt string (date-time)
startedBy string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skippedAt string (date-time)
skippedBy string
skipReason string
startedAt string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
startedBy string
submittedAt string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submittedBy string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string
succeededAt string (date-time)
succeededBy string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

startedAt string (date-time): Optional because a step can reach ERRORED without having been started
startedBy string
submittedAt string (date-time): Optional because a step can be errored before being submitted
submittedBy string
erroredAt string (date-time)
erroredBy string
error string
skippedAt string (date-time): Optional because a step could be skipped but then error while running completion actions
skippedBy string
skipReason string
succeededAt string (date-time): Optional because a step can succeed but then error while running completion actions
succeededBy string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/channel-capture-status" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "channelCaptureStatus": {
    "outputFieldId": "<output field id>",
    "captureMoment": "CAPTURE_MOMENT_STEP_START",
    "inProgress": {
      "startedAt": "2026-01-01T00:00:00Z"
    }
  }
}'

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/channel-capture-status",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "channelCaptureStatus": {
            "outputFieldId": "<output field id>",
            "captureMoment": "CAPTURE_MOMENT_STEP_START",
            "inProgress": {"startedAt": "2026-01-01T00:00:00Z"},
        },
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/channel-capture-status",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "channelCaptureStatus": {
            "outputFieldId": "<output field id>",
            "captureMoment": "CAPTURE_MOMENT_STEP_START",
            "inProgress": {"startedAt": "2026-01-01T00:00:00Z"},
        },
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/channel-capture-status",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "channelCaptureStatus": {
                    "outputFieldId": "<output field id>",
                    "captureMoment": "CAPTURE_MOMENT_STEP_START",
                    "inProgress": {"startedAt": "2026-01-01T00:00:00Z"},
                },
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedureRid": "<procedure rid>",
      "procedureCommitId": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedBy": "<updated by>",
      "updatedAt": "2026-01-01T00:00:00Z",
      "startedAt": "2026-01-01T00:00:00Z",
      "startedBy": "<started by>",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finishedBy": "<finished by>",
      "abortedAt": "2026-01-01T00:00:00Z",
      "abortedBy": "<aborted by>",
      "failedAt": "2026-01-01T00:00:00Z",
      "failedBy": "<failed by>",
      "failedReason": "<failed reason>",
      "assetRids": [
        "<asset rids>"
      ],
      "isArchived": true
    },
    "state": {
      "globalFields": {
        "<key>": {
          "assetRid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "templateNodeId": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "templateCommitId": "<template commit id>"
          }
        }
      },
      "sectionEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      },
      "stepEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Repeat step#

PUT /procedures/v1/executions/{procedureExecutionRid}/steps/{stepId}/repeat

Repeat a previously finished step in a procedure execution. This can only be done if the given step is in state SUCCEEDED, SKIPPED or ERRORED. Other state transitions are managed by the backend.

Path parameters

procedureExecutionRid string required
stepId string required: The unique identifier of the execution step to repeat/duplicate. At least 1 character.

Body

behavior RepeatStepBehavior

Behavior for how repeating the step will affect dependants.

Values of RepeatStepBehavior

REPEAT_STEP_BEHAVIOR_UNSPECIFIED
REPEAT_STEP_BEHAVIOR_ISOLATED: The targeted step will be repeated, but the original graph will be preserved and only direct children will be checked for state updates

value StepContentValue

Setting the value of the step’s content.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait required

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields required

asset

asset AssetFieldValue

Fields of AssetFieldValue

assetReference AssetReference

Fields of AssetReference

one of rid, fieldId required

rid

rid string: a constant AssetRid

fieldId

fieldId string: The field reference that will contain an AssetRid value. The execution will fail if the field is not set but the value is accessed.

checkbox

checkbox CheckboxFieldValue

Fields of CheckboxFieldValue

value boolean: Default to false if not set

text

text TextFieldValue

Fields of TextFieldValue

value string: Default to empty string if not set

int

int IntFieldValue

Fields of IntFieldValue

value string (int64)

double

double DoubleFieldValue

Fields of DoubleFieldValue

value number

singleEnum

singleEnum SingleEnumFieldValue

Fields of SingleEnumFieldValue

value string: Default to empty string if not set

multiEnum

multiEnum MultiEnumFieldValue

Fields of MultiEnumFieldValue

value array of string: Default to empty list if not set

fileUpload

fileUpload FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUpload

multiFileUpload MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

startIngest

startIngest StartIngestStepValue

Fields of StartIngestStepValue

ingestJobRid string: The RID of the ingest job that was started by the client. This must be populated for the step to be submitted.

selectOrCreateAsset

selectOrCreateAsset SelectOrCreateAssetStepValue

Fields of SelectOrCreateAssetStepValue

assetReference AssetReference: The asset that was selected / created by the client. This must be populated for the step to be submitted.

wait

wait WaitStepValue: …

autoProceedConfig AutoProceedConfig

Set whether the step has auto-proceed enabled.

Fields of AutoProceedConfig

one of disabled, enabled required

disabled

disabled Disabled: The step will not be automatically completed

enabled

enabled Enabled: The step will automatically submit the step contents once the requirements are met and begin the transition to either PASSED or ERRORED.

targetState TargetStepStateRequest

Setting the state of the step. This will occur after the other updates in this request.

Fields of TargetStepStateRequest

one of inProgress, submitted, skipped, errored required

inProgress

inProgress StepInProgressRequest

submitted

submitted StepSubmittedRequest

skipped

skipped StepSkippedRequest

Fields of StepSkippedRequest

skipReason string

errored

errored StepErroredRequest

Fields of StepErroredRequest

errorReason string

Response

procedureExecution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

Fields of ProcedureExecutionState

globalFields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

assetRid

assetRid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

stringValue

stringValue string

doubleValue

doubleValue number

booleanValue

booleanValue boolean

intValue

intValue string (int64)

stringsValue

stringsValue Strings

Fields of Strings

values array of string

ingestJobRid

ingestJobRid string

runRid

runRid string

fileUploadValue

fileUploadValue FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUploadValue

multiFileUploadValue MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
templateNodeId string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
templateCommitId string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

templateNodeId string

Unique identifier of the template node this execution node is based on. At least 1 character.

isOutdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

notStarted

notStarted ExecutionStepNotStarted

inProgress

inProgress ExecutionStepInProgress

Fields of ExecutionStepInProgress

startedAt string (date-time)
startedBy string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skippedAt string (date-time)
skippedBy string
skipReason string
startedAt string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
startedBy string
submittedAt string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submittedBy string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string
succeededAt string (date-time)
succeededBy string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

startedAt string (date-time): Optional because a step can reach ERRORED without having been started
startedBy string
submittedAt string (date-time): Optional because a step can be errored before being submitted
submittedBy string
erroredAt string (date-time)
erroredBy string
error string
skippedAt string (date-time): Optional because a step could be skipped but then error while running completion actions
skippedBy string
skipReason string
succeededAt string (date-time): Optional because a step can succeed but then error while running completion actions
succeededBy string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/repeat" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "behavior": "REPEAT_STEP_BEHAVIOR_ISOLATED",
  "value": {
    "form": {
      "fields": [
        {
          "asset": {
            "assetReference": {
              "rid": "<rid>"
            }
          }
        }
      ]
    }
  },
  "autoProceedConfig": {
    "disabled": {}
  },
  "targetState": {
    "inProgress": {}
  }
}'

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/repeat",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "behavior": "REPEAT_STEP_BEHAVIOR_ISOLATED",
        "value": {"form": {"fields": [{"asset": {"assetReference": {"rid": "<rid>"}}}]}},
        "autoProceedConfig": {"disabled": {}},
        "targetState": {"inProgress": {}},
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/repeat",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "behavior": "REPEAT_STEP_BEHAVIOR_ISOLATED",
        "value": {"form": {"fields": [{"asset": {"assetReference": {"rid": "<rid>"}}}]}},
        "autoProceedConfig": {"disabled": {}},
        "targetState": {"inProgress": {}},
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/repeat",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "behavior": "REPEAT_STEP_BEHAVIOR_ISOLATED",
                "value": {
                    "form": {
                        "fields": [{"asset": {"assetReference": {"rid": "<rid>"}}}],
                    },
                },
                "autoProceedConfig": {"disabled": {}},
                "targetState": {"inProgress": {}},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedureRid": "<procedure rid>",
      "procedureCommitId": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedBy": "<updated by>",
      "updatedAt": "2026-01-01T00:00:00Z",
      "startedAt": "2026-01-01T00:00:00Z",
      "startedBy": "<started by>",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finishedBy": "<finished by>",
      "abortedAt": "2026-01-01T00:00:00Z",
      "abortedBy": "<aborted by>",
      "failedAt": "2026-01-01T00:00:00Z",
      "failedBy": "<failed by>",
      "failedReason": "<failed reason>",
      "assetRids": [
        "<asset rids>"
      ],
      "isArchived": true
    },
    "state": {
      "globalFields": {
        "<key>": {
          "assetRid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "templateNodeId": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "templateCommitId": "<template commit id>"
          }
        }
      },
      "sectionEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      },
      "stepEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Update step#

PUT /procedures/v1/executions/{procedureExecutionRid}/steps/{stepId}/update

Update the status of a step in a procedure execution. This can only be done if the step is NOT_STARTED, IN_PROGRESS, or SUBMITTED. Other state transitions are managed by the backend.

Path parameters

procedureExecutionRid string required
stepId string required: The unique identifier of the execution step to update. At least 1 character.

Body

value StepContentValue

Setting the value of the step’s content. This is only allowed if the step is NOT_STARTED or IN_PROGRESS.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait required

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields required

asset

asset AssetFieldValue

Fields of AssetFieldValue

assetReference AssetReference

Fields of AssetReference

one of rid, fieldId required

rid

rid string: a constant AssetRid

fieldId

fieldId string: The field reference that will contain an AssetRid value. The execution will fail if the field is not set but the value is accessed.

checkbox

checkbox CheckboxFieldValue

Fields of CheckboxFieldValue

value boolean: Default to false if not set

text

text TextFieldValue

Fields of TextFieldValue

value string: Default to empty string if not set

int

int IntFieldValue

Fields of IntFieldValue

value string (int64)

double

double DoubleFieldValue

Fields of DoubleFieldValue

value number

singleEnum

singleEnum SingleEnumFieldValue

Fields of SingleEnumFieldValue

value string: Default to empty string if not set

multiEnum

multiEnum MultiEnumFieldValue

Fields of MultiEnumFieldValue

value array of string: Default to empty list if not set

fileUpload

fileUpload FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUpload

multiFileUpload MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

startIngest

startIngest StartIngestStepValue

Fields of StartIngestStepValue

ingestJobRid string: The RID of the ingest job that was started by the client. This must be populated for the step to be submitted.

selectOrCreateAsset

selectOrCreateAsset SelectOrCreateAssetStepValue

Fields of SelectOrCreateAssetStepValue

assetReference AssetReference: The asset that was selected / created by the client. This must be populated for the step to be submitted.

wait

wait WaitStepValue: …

autoProceedConfig AutoProceedConfig

Set whether the step has auto-proceed enabled. This is only allowed if the step is NOT_STARTED. or IN_PROGRESS.

Fields of AutoProceedConfig

one of disabled, enabled required

disabled

disabled Disabled: The step will not be automatically completed

enabled

enabled Enabled: The step will automatically submit the step contents once the requirements are met and begin the transition to either PASSED or ERRORED.

targetState TargetStepStateRequest

Setting the state of the step. This will occur after the other updates in this request.

Fields of TargetStepStateRequest

one of inProgress, submitted, skipped, errored required

inProgress

inProgress StepInProgressRequest

submitted

submitted StepSubmittedRequest

skipped

skipped StepSkippedRequest

Fields of StepSkippedRequest

skipReason string

errored

errored StepErroredRequest

Fields of StepErroredRequest

errorReason string

Response

procedureExecution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedureRid string: The procedure template rid this execution is based on.
procedureCommitId string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
createdBy string
createdAt string (date-time)
updatedBy string
updatedAt string (date-time)
startedAt string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
startedBy string
finishedAt string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finishedBy string
abortedAt string (date-time): Will be true/set if the execution is the ABORTED terminal state.
abortedBy string
failedAt string (date-time): Will be set if the execution is in the ERRORED terminal state.
failedBy string
failedReason string
assetRids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
isArchived boolean

Fields of ProcedureExecutionState

globalFields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

assetRid

assetRid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

stringValue

stringValue string

doubleValue

doubleValue number

booleanValue

booleanValue boolean

intValue

intValue string (int64)

stringsValue

stringsValue Strings

Fields of Strings

values array of string

ingestJobRid

ingestJobRid string

runRid

runRid string

fileUploadValue

fileUploadValue FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUploadValue

multiFileUploadValue MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
templateNodeId string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
templateCommitId string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

templateNodeId string

Unique identifier of the template node this execution node is based on. At least 1 character.

isOutdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

notStarted

notStarted ExecutionStepNotStarted

inProgress

inProgress ExecutionStepInProgress

Fields of ExecutionStepInProgress

startedAt string (date-time)
startedBy string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skippedAt string (date-time)
skippedBy string
skipReason string
startedAt string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
startedBy string
submittedAt string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submittedBy string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

startedAt string (date-time)
startedBy string
submittedAt string (date-time)
submittedBy string
succeededAt string (date-time)
succeededBy string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

startedAt string (date-time): Optional because a step can reach ERRORED without having been started
startedBy string
submittedAt string (date-time): Optional because a step can be errored before being submitted
submittedBy string
erroredAt string (date-time)
erroredBy string
error string
skippedAt string (date-time): Optional because a step could be skipped but then error while running completion actions
skippedBy string
skipReason string
succeededAt string (date-time): Optional because a step can succeed but then error while running completion actions
succeededBy string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, startIngest, selectOrCreateAsset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/update" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "value": {
    "form": {
      "fields": [
        {
          "asset": {
            "assetReference": {
              "rid": "<rid>"
            }
          }
        }
      ]
    }
  },
  "autoProceedConfig": {
    "disabled": {}
  },
  "targetState": {
    "inProgress": {}
  }
}'

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/update",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "value": {"form": {"fields": [{"asset": {"assetReference": {"rid": "<rid>"}}}]}},
        "autoProceedConfig": {"disabled": {}},
        "targetState": {"inProgress": {}},
    },
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/update",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "value": {"form": {"fields": [{"asset": {"assetReference": {"rid": "<rid>"}}}]}},
        "autoProceedConfig": {"disabled": {}},
        "targetState": {"inProgress": {}},
    },
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/procedures/v1/executions/<procedure execution rid>/steps/<step id>/update",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "value": {
                    "form": {
                        "fields": [{"asset": {"assetReference": {"rid": "<rid>"}}}],
                    },
                },
                "autoProceedConfig": {"disabled": {}},
                "targetState": {"inProgress": {}},
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "procedureExecution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedureRid": "<procedure rid>",
      "procedureCommitId": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "createdBy": "<created by>",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedBy": "<updated by>",
      "updatedAt": "2026-01-01T00:00:00Z",
      "startedAt": "2026-01-01T00:00:00Z",
      "startedBy": "<started by>",
      "finishedAt": "2026-01-01T00:00:00Z",
      "finishedBy": "<finished by>",
      "abortedAt": "2026-01-01T00:00:00Z",
      "abortedBy": "<aborted by>",
      "failedAt": "2026-01-01T00:00:00Z",
      "failedBy": "<failed by>",
      "failedReason": "<failed reason>",
      "assetRids": [
        "<asset rids>"
      ],
      "isArchived": true
    },
    "state": {
      "globalFields": {
        "<key>": {
          "assetRid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "templateNodeId": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "templateCommitId": "<template commit id>"
          }
        }
      },
      "sectionEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      },
      "stepEdges": {
        "<key>": {
          "nodeIds": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Update procedure execution#

PUT /procedures/v1/executions/{procedureExecutionRid}/update

Heavy-handed update method for procedure execution.

Path parameters

procedureExecutionRid string required

Body

title string

description string

commitId string

labels LabelUpdateWrapper

Fields of LabelUpdateWrapper

labels array of string

properties PropertyUpdateWrapper

Fields of PropertyUpdateWrapper

properties map of string to string

Fields of ProcedureExecutionState

globalFields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

assetRid

assetRid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

stringValue

stringValue string

doubleValue

doubleValue number

booleanValue

booleanValue boolean

intValue

intValue string (int64)

stringsValue

stringsValue Strings

Fields of Strings

values array of string

ingestJobRid

ingestJobRid string

runRid

runRid string

fileUploadValue

fileUploadValue FileUploadFieldValue

Fields of FileUploadFieldValue

s3Upload S3UploadFileValue

Fields of S3UploadFileValue

s3Path string: The S3 path where the uploaded file is stored At least 1 character.
fileName string: The original filename of the uploaded file At least 1 character.
fileType string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multiFileUploadValue

multiFileUploadValue MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step required

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
templateNodeId string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
templateCommitId string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

templateNodeId string

Unique identifier of the template node this execution node is based on. At least 1 character.

isOutdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.