Calling the Verentis API

All Verentis APIs are reached through a single API gateway at api.<domain>. You send your scoped access token as a bearer token; the gateway routes the request to the right backend service.

Base URL

Never call a backend service directly — always go through the gateway.

Versioned routes

Endpoints are versioned in the path:

/v{version}/{resource}

For example /v1/workspaces or /v1/engines. Use the version documented for the endpoint you're calling.

Bearer authentication

Send the access token in the Authorization header:

GET /v1/workspaces HTTP/1.1
Host: api.localtest.me
Authorization: Bearer <access-token>
Accept: application/json

curl https://api.localtest.me/v1/workspaces \
  -H "Authorization: Bearer $TOKEN"

The token must carry the scope the endpoint requires (e.g. account.workspace.read). A token missing the scope is rejected — see Scopes & permissions.

Responses

Successful responses return JSON. List endpoints are paged and accept pageNo, pageSize and orderBy query parameters:

GET /v1/workspaces?pageNo=1&pageSize=20&orderBy=name HTTP/1.1
Authorization: Bearer <access-token>

A paged response includes the items plus paging metadata (total count, page number/size) so you can iterate.

Errors

Calling the API from the CLI

The Verentis CLI wraps the common surface (workspaces, users, API keys, files, executions, marketplace) in typed commands, and exposes everything else through an authenticated escape hatch — it signs in (device flow), mints the right access token per request, binds it to a workspace when needed, and renders errors for you:

verentis login     # device sign-in — approve in any browser (targets production by default)

verentis workspace list --json
verentis files ls /scripts --workspace <id>
verentis exec logs <executionId> --follow             # SSE log streaming

# Any endpoint, with automatic auth (like `gh api`):
verentis api GET /v1/engines --scope execution.execution.run
verentis api POST /v1/installations --workspace <id> --body @install.json \
  --scope marketplace.install.create --scope node.node.create

Next