Workspace API

Base URL:

https://api.provon.dev/v1

Authentication#

Workspace routes accept two credential types:

• Project API key — Authorization: Bearer <PROVON_API_KEY>. The key selects the project for public /v1/* routes. For project-qualified routes, the key must have access to the requested :projectId.
• Signed-in Workbench session — AuthJS session cookie. Used for /v1/projects/:projectId/* routes when the calling user has the required project permission.

Only the collection routes below are reachable from a project API key. Every other route in this page is session-only: it returns 401 UNAUTHORIZED ("workspace session required") when called with a bearer API key, because it depends on a signed-in human identity (membership role or onboarding state).

* POST /v1/organizations rejects project API keys outright: the actor must resolve as a signed-in user (or a user-bound access token), not a project API key. Callers that only hold a project API key cannot provision new organizations.

Project-scoped API keys also cannot create projects inside an organization they do not already belong to; the same assertOrganizationProjectCreateAllowed check that applies to browser users applies to bearer callers.

Organizations#

Collection routes accept both credential types. The remaining routes are session-only.

Create an organization:

curl -X POST "$PROVON_API_URL/organizations" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme AI"}'

Invite a member (session-only; role is one of OWNER, ADMIN, MEMBER, VIEWER):

curl -X POST "$PROVON_API_URL/organizations/$ORG_ID/invitations" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "colleague@example.com", "role": "MEMBER"}'

Projects#

GET /v1/projects and POST /v1/projects accept both credential types. The remaining routes are session-only.

Create a project:

curl -X POST "$PROVON_API_URL/projects" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"organizationId": "org_...", "name": "Production agents"}'

Project API Keys#

All project API key routes are session-only. They are used by the Workbench to mint, rename, and revoke keys and to attach per-key usage policies; a project API key cannot manage itself.

Create a key. The response includes the full secret once; store it immediately. When capabilities is omitted, the deployer grants the default set listed in Authentication.

curl -X POST "$PROVON_API_URL/projects/$PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $PROVON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI ingest key",
    "capabilities": ["telemetry:ingest"]
  }'

A usage policy body includes:

• metric — one of requests, tokens, or cost_usd.
• mode — one of rate_limit or budget.
• limitValue — positive number.
• windowPolicy — one of minute, hour, day, week, month, quarter, year, custom, or lifetime. When windowPolicy is custom, customWindowSeconds is required (positive integer); it is rejected for every other window policy.
• model — optional model name that scopes the policy to one model.
• enabled — optional boolean; when omitted on create the deployer defaults it to true.

Gateway Settings#

All Gateway settings routes are session-backed. Project Gateway settings configure provider keys, model policies, auto-router, guardrails, and observability.

For provider key and model-binding management from service clients, see Gateway API.

Integrations#

Project integrations connect Findings to issue trackers. All routes are session-backed.

Supported connector kinds are github, gitlab, linear, and jira.

Account And Workspace Setup#

These routes are session-backed and are used by the Workbench during onboarding and account management.

Errors#

Workspace errors use the common API error envelope:

{
  "error": {
    "code": "FORBIDDEN",
    "message": "actor cannot create projects in organization",
    "details": {}
  }
}

Common status codes: