List and inspect workflows

List a bounded set of workflows, then retrieve one resource by ID. This is a read-only way to practice collection controls and JSON:API resource identity. An empty collection is valid; the detail step is conditional on a workflow already existing.

What you will do

1. Request at most ten workflows with an explicit sort and sparse fieldset.
2. Verify 200, x-api-version, x-request-id, and the data array.
3. If a workflow exists, extract its ID without logging the bearer token.
4. Retrieve that workflow at its canonical item path.

Prerequisites

• Complete Make your first API request.
• Keep HODOFLOW_BASE_URL and TOKEN in a trusted process environment.
• Use a service account with api_read and an active run-as member in the workspace you intend to inspect.
• Install cURL and jq.

The workflow list reveals only objects visible in the service account's stored workspace and allowed to its run-as member.

Request

Request a small page. --globoff prevents cURL from interpreting bracketed query keys:

WORKFLOWS_RESPONSE="$(
  curl --silent --show-error --globoff \
    --dump-header /dev/stderr \
    --header "Accept: application/vnd.api+json" \
    --header "Authorization: Bearer $TOKEN" \
    "$HODOFLOW_BASE_URL/api/json/v1/workflows?page[limit]=10&sort=name&fields[workflow]=name,is_active,version_number"
)"

printf '%s\n' "$WORKFLOWS_RESPONSE" | jq .

You should see a top-level data array containing zero to ten resources. Each resource still has type and id; the sparse fieldset restricts attributes to the requested public fields.

If a workflow exists, extract the first ID and retrieve it:

WORKFLOW_ID="$(printf '%s\n' "$WORKFLOWS_RESPONSE" | jq -er '.data[0].id')"

curl --silent --show-error \
  --header "Accept: application/vnd.api+json" \
  --header "Authorization: Bearer $TOKEN" \
  "$HODOFLOW_BASE_URL/api/json/v1/workflows/$WORKFLOW_ID" |
  jq .

Skip the detail request when .data is empty. Create a workflow through the application if the next exercise requires one; do not invent an ID.

Expected response

The collection returns 200 OK, x-api-version: v1, and a non-empty x-request-id. A populated response resembles:

{
  "data": [
    {
      "type": "workflow",
      "id": "00000000-0000-4000-8000-000000000001",
      "attributes": {
        "name": "Order intake",
        "is_active": true,
        "version_number": 3
      }
    }
  ],
  "jsonapi": { "version": "1.0" },
  "links": {
    "next": null,
    "prev": null,
    "self": "https://hodoflow.com/api/json/v1/workflows?page[limit]=10"
  }
}

The detail response has one data object with the same type and id. Its attributes may be broader because the second request did not send a sparse fieldset.

Troubleshooting

• 401: discard the cached token, exchange once, and retry once.
• 403: grant api_read or correct the run-as membership; retries cannot add access.
• 404 on the detail path: re-read the ID in the same workspace. It may be absent or hidden by object authorization.
• 400/422: compare filter, sort, and field names with the workflow reference.
• 429: wait for Retry-After, then repeat the read.
• Empty data: authentication succeeded; create product state only if your next task needs it.

Unset WORKFLOW_ID and WORKFLOWS_RESPONSE when finished if local policy treats resource data as sensitive.

Next steps

• Follow a workflow run after the workflow executes.
• Learn pagination and filtering.
• Open the Workflows API reference for every operation and field.