API Reference

RunEnv publishes a reviewed, machine-readable API contract at /openapi.json. The contract is intentionally opt-in: it documents supported public operations rather than every internal, dashboard, cron, or compatibility route.

Agent Guard API

The currently published contract covers Agent Guard, RunEnv's credentialless action control plane for AI agents. It supports discovering capabilities, previewing an exact action, requesting a short-lived permit, executing an approved action, and reading a redacted status or receipt.

Agents do not receive connector credentials or a general secret-read API through this contract.

Authentication

Agent Guard uses OAuth 2.1 authorization-code flow with PKCE S256. Discover the deployment-specific OAuth metadata instead of hard-coding endpoints:

  • /.well-known/oauth-authorization-server
  • /.well-known/oauth-protected-resource
  • /.well-known/jwks.json

The documented operations declare their required OAuth scope in OpenAPI. RunEnv checks the scope, project binding, Cedar policy, preview binding, permit state, approval requirement, and connector status before executing an external action.

Safe action workflow

  1. Call GET /api/agent-gateway/v1/capabilities to discover the broker actions available to the authenticated project identity.
  2. Call POST /api/agent-gateway/v1/actions/preview with a bounded action request and human-readable reason.
  3. Call POST /api/agent-gateway/v1/permits for the returned preview.
  4. If approval is required, wait for the permit to become executable. Do not retry with a different action or broader scope.
  5. Call POST /api/agent-gateway/v1/actions with the one-use permit and an idempotency key.
  6. Poll GET /api/agent-gateway/v1/actions/{actionId} for redacted status and receipt metadata.

Use the AI Agent Integrations guide for a supported coding-agent setup. Do not send secret values, service tokens, connector credentials, authorization codes, or refresh tokens in prompts or action arguments.

Compatibility note

RunEnv also has CLI, SDK, dashboard, and organization APIs with their own authentication and authorization boundaries. They are not automatically safe for an AI agent merely because a human developer can use them. This public contract expands only after the operation owner, route validation, authorization test, and safe examples have been reviewed together.

Human and automation clients

The Dashboard, CLI, SDKs, and Desktop app use their own authenticated API families. These routes are for their supported clients and are not a substitute for the public OpenAPI contract.

  • Project and environment management is performed through the authenticated Dashboard/API boundary.
  • CLI authentication and runtime retrieval use CLI-specific API routes and token scopes.
  • Audit history and environment metadata are returned only after authorization for the selected organization and project.

For supported automation, use the documented CLI, SDK, or Agent Guard workflow rather than calling an internal-looking route copied from a browser session.