API for Agents

What it is

The PetroBench REST API gives scripts, agents and internal systems direct HTTP access to the same data and actions as the web app: wells, equipment, simulations, imports, exports and account data. It is versioned under /api/v1, returns JSON, and is described by an OpenAPI specification.

Use the API when you need scheduled or unattended work, bulk operations, or full control over each request. Use MCP when a person is working with an AI client.

Base URL

How it works

• Authentication: Every request carries a Bearer token. Use a personal API token, a division service token, or an OAuth access token.
• Permissions: The token's scopes decide which endpoints it can call, and the owner's role decides which records it can see. A token never sees more than its owner can see in the web app.
• Organization: Users in more than one organization send X-Organization-Id, or pin the token to one organization when they create it.
• Long-running work: Simulations, imports and exports run as jobs. The API returns a job ID, and you poll it or subscribe to a webhook for the result.
• Rate limits: Limits apply per token and per division. Every response includes X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.
• Audit: Every request is logged with the token and user. Service tokens can name the person they act for, so the audit log shows who triggered the call.

Use cases

• Keep well data in sync with your system of record

  A nightly job updates wells, rod strings, tubing and pumping units from your own database.

  wells:read, wells:write

• Run simulations in bulk

  A script starts simulations for a set of wells and collects the results as each job completes.

  simulations:run, simulations:read

• Feed dashboards and reports

  Your BI tool or data warehouse pulls well data and simulation results on a schedule.

  wells:read, simulations:read

• React to events

  A signed webhook tells your system when a simulation finishes or a well changes, so nothing has to poll.

  wells:read, wells:write

• Build your own agent

  Your agent framework calls the API directly, with a person approving any write.

  wells:read, simulations:read

• Monitor usage

  Pull API usage and account data into your own monitoring.

  organization:read

Create a token

Use a service token for long-running automation and a personal API token for your own testing.

curl -sS -H "Authorization: Bearer $PB_TOKEN" \
  https://app.petrobench.com/api/v1/me

Good practice for agents

• Send Authorization: Bearer <token> on every call.
• Multi-org users: set X-Organization-Id when required (see Authentication).
• Respect rate limits and surface Retry-After to your agent loop.
• Prefer idempotent reads first; gate writes behind human approval in the agent policy.

References

These references require a docs login.

Next

• MCP for Agents
• AI and MCP Controls