Bentra API - Bentra

The Bentra API lets scripts, integrations and AI agents do what people do in the Bentra UI: create and configure workflows, submit and approve requests, trigger and follow runs, and administer the organization. The Bentra MCP server is built on it. Every call acts as a user and can only do what that user can do in the UI.

Base URL

https://<bentra-host>/orgs/<org-id>/api/v1/

Paths on these pages are relative to that base. Swagger UI for your organization is at /orgs/<org-id>/api/v1/docs/ when you’re signed in.

Authentication

Send a token as a bearer token:

curl -H "Authorization: Bearer $BENTRA_TOKEN" \
  https://bentra.example.com/orgs/k3j9x2m4pqrt/api/v1/workflows/

Token	How you get it	What it can do
Personal access token	Settings → API Access in Bentra. Shown once. See API tokens.	Everything its user can do.
AI agent (delegated) token	Issued to the Bentra MCP server when you connect an agent. Short-lived.	Everything its user can do through the scopes below, except skipping approval.

A token belongs to one organization; using it on another organization’s URL returns 401.

Scopes

Personal tokens carry * (all scopes). Delegated tokens carry the named scopes, and every endpoint lists the scope it needs. Scopes narrow what a token can reach; they never grant more than the user’s own permissions.

Scope	Allows
`read:workflows`	View workflows, settings, files, approvers, form visibility.
`edit:workflows`	Create workflows, change their details and settings, edit files, publish versions.
`manage:workflow_access`	Change approvers, workflow roles and form visibility.
`read:variables` / `edit:variables`	View or change variable collections and workflow variables.
`read:runs` / `manage:runs`	View runs; re-run or cancel them.
`trigger:workflow_runs`	Trigger job runs.
`read:requests`	View requests.
`submit:workflow_requests`	Submit, update and cancel your own requests.
`approve:workflow_requests`	Approve, reject or request changes where you’re a designated approver.
`comment:requests`	Comment on requests you can view.
`skip:workflow_approval`	Submit without approval (personal tokens only).
`manage:data_sharing`	Change a job’s dataset sharing.
`read:org`	View workspaces, members, groups, connectors, runner pools and branding.
`manage:org`	Change organization details, request-portal branding and single sign-on.
`manage:connectors`	Rename connectors, move them to another workspace, change who they’re shared with, and test their connection.
`manage:workspaces`	Create, rename and delete workspaces.
`manage:members`	Invite and remove members, change roles, manage groups and workspace access.

What stays in the UI

Anything that takes or mints a secret stays in the UI: adding VCS connectors or changing their credentials, runner tokens and personal API tokens. You can list connectors and runner pools so you can choose one, and rename, move or re-share a connector. Single sign-on is partly here: domains, provisioning and setup links, but a person connects the identity provider in the WorkOS assistant.

Conventions

Pagination. Lists return {"count", "next", "previous", "results"}. Use page and page_size (default 25, max 100). Success. Writes return {"success": true, ...} with the changed object, 201 on create. Deletes return 204 or {"success": true}. Errors.

Status	Meaning	Body
`400`	Invalid input	`{"success": false, "errors": {"field": "message"}}` or `{"success": false, "error": "..."}`
`401`	Missing, revoked or expired token	`{"detail": "..."}`
`403`	Missing scope or permission	`{"detail": "..."}` or `{"success": false, "error": "..."}`
`404`	Doesn’t exist, or you can’t see it	`{"detail": "Not found."}`
`409`	Not allowed in the object’s current state (e.g. workflow paused)	`{"success": false, "error": "...", "code": "..."}`
`429`	Rate limited	`{"detail": "..."}`
`502`	The VCS provider returned an error	`{"success": false, "error": "..."}`

Naming people and groups. Where a body takes a user, pass a user id, username or email of a member of the organization. Where it takes a group, pass the group’s id or name.

Resources

Organization: connectors, repositories, branches and tags, runner pools, portal branding
Administration: organization details, members, invitations, workspaces, groups
Workflows: create (local or repo-backed), details, settings, schedule, status
Workflow access: approvers, roles, form visibility
Files and versions: files of Bentra-stored workflows, publishing and pinning versions
Variables: variable collections and workflow variables
Requests: submit, follow, comment, update, approve
Runs: trigger jobs, follow runs, logs, re-run, cancel
Job datasets: versions, promote, freeze, data scope and read grants
Single sign-on: status, allowed domains, member provisioning, setup links

​Base URL

​Authentication

​Scopes

​What stays in the UI

​Conventions

​Resources