The Rod-Lift Engineering API

Versioned REST endpoints your scripts and services call directly. Same Bearer token and scopes as MCP and Vector.

Request workbench app.petrobench.com/api/v1

GET /api/v1/wells

Scope wells:read

Response Ready

                {
  "data": [
    { "id": "well_demo_a", "name": "Demo Well A", "status": "active" },
    { "id": "well_demo_b", "name": "Demo Well B", "status": "active" }
  ],
  "cursor": "eyJwYWdlIjoyfQ=="
}

GET /api/v1/simulations/sim_8f2a

Scope simulations:read

Response Ready

                {
  "id": "sim_8f2a",
  "well_id": "well_demo_a",
  "status": "completed",
  "peak_polished_rod_load_lb": 29228
}

POST /api/v1/simulations

Scope simulations:run

Response Ready

                {
  "id": "sim_9c11",
  "status": "queued",
  "poll": "/api/v1/simulations/sim_9c11"
}

Scenario UI, illustrative request and response shapes.

API Programmatic Access to Your Data

Rod-Lift Wells, Sims, and Equipment Over HTTP

The callable REST surface for wells, simulations, and equipment. Mint a scoped token once - use it here or on MCP.

Base URL https://app.petrobench.com/api/v1

One Versioned Surface

Wells, simulations, equipment, and organization data behind a single stable base URL. No scraping the app, no brittle exports.

The Same Answer, Everywhere

REST reads the same records that power the platform UI and MCP tools. What your engineers see is what the API returns.

OpenAPI 3.1 and Scoped Tokens

OpenAPI 3.1, scoped Bearer tokens, cursor pagination, and a structured error envelope. Predictable shapes for generated clients.

Auth Same Scopes as MCP

One Token. Only the Abilities You Mint

Every route checks a scoped ability before it answers. Mint in Settings or with the pb CLI. REST and MCP enforce the same strings

Credential Settings, pb CLI

Authorization


Bearer pb_pat_8f2a9c…

Scopes

wells:read
wells:write
simulations:read
simulations:run
equipment:read
organization:read

Personal tokens follow the user. Service tokens use the pb_svc_ prefix for machine-to-machine callers

Catalog Resource Catalog

The Domain, Mapped to Routes

Wells, sims, equipment, and org context on one versioned surface, the same records the platform and MCP already use

Wells
Full wellbore record

Surveys, perfs, casing, rods, units, performance, field data
Simulations
Runs, versions, results

Versions, results, IPR, comparisons
Equipment
Catalog and installed hardware

Shared catalog and what is installed downhole
Organization
Structure and context

Regions, tags, account
Operations
Jobs and reporting

Async jobs and simulation results
Governance
Tokens and audit

Mint in Settings or pb CLI, audit logs

Quickstart Your First Request

Read Your Wells in Three Lines

Scoped Bearer token, one resource, structured JSON, curl, Python, or TypeScript

GET /api/v1/wells

# list wells your token can see

curl https://app.petrobench.com/api/v1/wells \
  -H "Authorization: Bearer pb_svc_..."

import requests

resp = requests.get(
    "https://app.petrobench.com/api/v1/wells",
    headers={"Authorization": "Bearer pb_svc_..."},
)
resp.raise_for_status()
wells = resp.json()

const res = await fetch("https://app.petrobench.com/api/v1/wells", {
  headers: { Authorization: "Bearer pb_svc_..." },
});

const wells = await res.json();

Responses are cursor-paginated JSON. Follow the returned cursor to walk the full set

Next Same Engine, Other Surfaces