Skip to content

DRP REST API

Digital Rebar Provision exposes a full REST API at /api/v3 on the DRP endpoint. The base URL pattern is https://<drp-host>:8092/api/v3/<resource> where <resource> is the plural name of the object type (e.g., machines, tasks, workflows, stages, bootenvs). All requests and responses use application/json content type. The complete API is defined as an OpenAPI (Swagger) specification available at https://<drp-host>:8092/swagger.json, and a browsable UI is accessible at https://<drp-host>:8092/swagger-ui/.

Authentication

The DRP API uses token-based authentication. Obtain a token by posting credentials to /api/v3/users/<username>/token:

Bash
# Obtain an auth token (returns JSON with Token field)
curl -sk -X GET \
  "https://drp.example.com:8092/api/v3/users/rocketskates/token?ttl=3600" \
  -u rocketskates:r0cketsk8ts

The returned Token value is a signed JWT. Pass it in subsequent requests via the Authorization header:

Text Only
Authorization: Bearer <token>

Alternatively, HTTP Basic authentication (-u username:password) is accepted for quick interactive use, but token-based auth is preferred for automation because it supports fine-grained TTL and role-scoped claims.

Discovering Endpoints

Browse the live Swagger UI at https://<drp-host>:8092/swagger-ui/ to see all available endpoints, their parameters, and request/response schemas. The raw OpenAPI spec can be downloaded:

Bash
curl -sk https://drp.example.com:8092/swagger.json | jq '.paths | keys[]' | head -30

drpcli itself is a thin wrapper around the same API — reading its source or running drpcli <object> --help is another way to discover the available operations for each resource type.

Common API Operations

List all machines

Bash
TOKEN=$(curl -sk -u rocketskates:r0cketsk8ts \
  "https://drp.example.com:8092/api/v3/users/rocketskates/token?ttl=600" \
  | jq -r .Token)

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://drp.example.com:8092/api/v3/machines" | jq '.[].Name'

Get a single machine by UUID

Bash
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://drp.example.com:8092/api/v3/machines/<machine-uuid>" | jq .

Update a param on a machine

Bash
# Set a parameter value directly on the machine object
curl -sk -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"op":"add","path":"/Params/my-param","value":"my-value"}]' \
  "https://drp.example.com:8092/api/v3/machines/<machine-uuid>"

Parameters can also be managed via the dedicated params sub-resource:

Bash
# Set a single param via the params sub-resource
curl -sk -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '"my-value"' \
  "https://drp.example.com:8092/api/v3/machines/<machine-uuid>/params/my-param"

Filtering and Pagination

The list endpoints support server-side filtering via query parameters. Filters follow the pattern ?<field>=<value> and can be combined. JSON path filters use the ?<jsonpath>=<value> syntax:

Bash
# List only machines currently in a specific workflow
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://drp.example.com:8092/api/v3/machines?Workflow=ubuntu-install"

# List machines with a specific stage
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://drp.example.com:8092/api/v3/machines?Stage=discover"

Use drpcli for day-to-day scripting since it handles token management, TLS, and JSON formatting automatically. Use the raw REST API when integrating DRP with external tools, webhooks, or languages without a native DRP client library.