API v1 · Stable contract

Connect maintenance to the rest of the business.

Build ERP, accounting, notification, and future mobile workflows on scoped credentials, predictable errors, and signed events.

Download OpenAPI 3.1 ↗Manage integrations

REQUEST / 200184 ms

GET /api/v1/assets?status=active
Authorization: Bearer forge_live_••••••

{
  "data": [{
    "asset_tag": "PMP-104",
    "name": "Boiler feed pump",
    "status": "active"
  }],
  "meta": { "count": 1, "limit": 50 }
}

Keys stay narrow.

Seven explicit scopes, per-key expiry, rotation, immediate revocation, and SHA-256 digests at rest.

Failures stay legible.

Every error has a stable code, human message, request ID, and bounded validation details.

Events stay verifiable.

HMAC-SHA256 signatures, delivery IDs, timestamps, exponential backoff, and a dead-letter trail.

Quickstart

One key. One scoped request.

1
Create an API key
An Admin opens Developer in Revolution Road, names the integration, chooses only its required scopes, and copies the one-time secret.
2
Send the bearer token
Call your Revolution Road host over HTTPS. Never put the key in a query string, browser bundle, spreadsheet, or repository.
3
Trace every response
Persist the response request ID in connector logs and honor rate-limit headers before retrying.

cURL · list active assetsassets:read

curl "https://your-forge-host.example.com/api/v1/assets?status=active" \
  --header "Authorization: Bearer $FORGE_API_KEY" \
  --header "Accept: application/json"

Reference

Versioned endpoints

MethodPathScopePurpose

GET/api/v1/assetsassets:read

Search and list organization assets

POST/api/v1/assetsassets:write

Create an asset

PATCH/api/v1/assets/{id}assets:write

Update one asset

GET/api/v1/work-orderswork_orders:read

List work orders

POST/api/v1/work-orderswork_orders:write

Create a work order

PATCH/api/v1/work-orders/{id}work_orders:write

Update or advance work

GET/api/v1/exports/assets.csvexports:read

ERP-ready asset CSV

GET/api/v1/exports/work-orders.csvexports:read

Accounting and work CSV

POST/api/v1/imports/assetsimports:write

Validate and upsert asset CSV

GET/api/v1/webhookswebhooks:manage

List signed event subscriptions

POST/api/v1/webhookswebhooks:manage

Create a signed subscription

The /api/v1 contract remains stable within version 1. Additive fields may appear; clients should ignore fields they do not use.

Outbound events

Verify before processing.

Revolution Road signs the exact body as HMAC_SHA256(secret, timestamp + "." + body). Reject stale timestamps and compare signatures without timing leaks.

Node.js · verify deliveryHMAC-SHA256

import { createHmac, timingSafeEqual } from "node:crypto";

const timestamp = request.headers.get("x-forge-timestamp");
const received = request.headers.get("x-forge-signature").slice(3);
const expected = createHmac("sha256", process.env.FORGE_WEBHOOK_SECRET)
  .update(timestamp + "." + rawBody).digest("hex");

if (!timingSafeEqual(Buffer.from(received), Buffer.from(expected))) {
  throw new Error("Invalid Revolution Road signature");
}

x-forge-eventEvent type, such as cmms.status.changed

x-forge-deliveryStable event ID for deduplication

x-forge-timestampUnix seconds included in the signature

x-forge-signaturev1-prefixed SHA-256 HMAC

ERP + accounting

Move data without losing control.

Exports cap at 10,000 rows and neutralize spreadsheet-formula prefixes. Asset imports accept up to 1,000 rows or 2 MB, validate every row first, and upsert by asset_tag.

CSV · asset importtext/csv

asset_tag,name,status,location,metadata
PMP-104,Boiler feed pump,active,Boiler room,"{""erp_id"":""EQ-9081""}"
AHU-12,North air handler,active,Roof,"{}"

Enterprise bridge

Federation without premature exposure.

OIDCBroker-ready contract

Issuer, domain hint, and connection state are organization-scoped and disabled until an identity provider is connected.

SAMLMetadata-ready contract

Per-organization metadata URLs are stored without exposing provider credentials to the browser.

SCIM 2.0Provisioning-ready tokens

Token digests and lifecycle fields are prepared for enterprise provisioning endpoints in a controlled rollout.

Need a connector?

Start from the contract, then keep the scope small.

Read the integration guide