Reference

Workspace web API reference

Understand the versioned endpoints used by the authenticated Impact Gate website.

6 min readProduct guide

On this page

Scope and authentication#

The website uses the same-origin /api/v1 workspace API. This reference describes its current application contract for understanding integrations and diagnostics. The release does not provide public API keys, a machine-account workflow, or a supported automation SDK.

Protected routes require a Firebase ID token for the signed-in identity and enforce workspace membership. Write routes also require a verified email and an owner or admin role. The website handles token acquisition and refresh through its authentication client.

Configuration and session#

Method	Path	Response / purpose
GET	/api/v1/config	Public versioned configuration, enabled sign-in methods, and GitHub App installation URL.
GET	/api/v1/session	Authenticated identity, authorized workspace memberships, and deployment capabilities.

Read public sign-in methods

const response = await fetch('/api/v1/config', { cache: 'no-store' });
if (!response.ok) throw new Error('Configuration unavailable');
const config = await response.json();
console.log(config.methods); // ['google', 'email-link'] on this deployment

A session response has version: 1, user, workspaces, and capabilities. Each workspace contains an ID, name, role, installation ID, account login, and installation status. runtimeTelemetry indicates whether runtime connections are supported. externalModels indicates the deployment's external model capability.

Workspace endpoints#

In the paths below, {workspaceId} and {repositoryId} are application UUIDs returned by the workspace API. GitHub's numeric repository IDs are used when saving repository selection. These are different identifiers.

Method	Path	Purpose
GET	/api/v1/workspaces/{workspaceId}/repositories/available	List available installation repositories and current selection flags.
PUT	/api/v1/workspaces/{workspaceId}/repositories	Replace the selection using unique numeric GitHub repository IDs; at most 100.
GET	/api/v1/workspaces/{workspaceId}/snapshot	Read repositories, services, endpoints, edges, findings, candidates, jobs, and settings.
POST	/api/v1/workspaces/{workspaceId}/repositories/{repositoryId}/index	Queue indexing for a selected, available repository.
PATCH	/api/v1/workspaces/{workspaceId}/settings	Save permitted preferences using the currently displayed settings version.
POST	/api/v1/workspaces/{workspaceId}/candidates/{endpointId}/review	Record or remove an evidence review for the specified snapshot.
GET	/api/v1/workspaces/{workspaceId}/runtime	Read sanitized Prometheus/Datadog connection status and configuration.
POST	/api/v1/workspaces/{workspaceId}/runtime/{provider}/test	Test a source and preview endpoint matches without saving.
POST	/api/v1/workspaces/{workspaceId}/runtime/{provider}/discover	Discover source service names and suggest indexed service matches without saving; mappings may be empty.
PUT	/api/v1/workspaces/{workspaceId}/runtime/{provider}	Test and save source configuration, encrypted credentials and observations.
POST	/api/v1/workspaces/{workspaceId}/runtime/{provider}/sync	Refresh evidence with the saved connection.
DELETE	/api/v1/workspaces/{workspaceId}/runtime/{provider}	Remove a source and its imported evidence.

Repository selection body — illustrative IDs

{
  "repositoryIds": [123456789, 987654321]
}

Saving repository selection returns a workspace snapshot. Queueing an index returns a job record. A snapshot includes version: 1, its workspace and snapshot identifiers, generation time, and the recorded workspace collections. Consumers must verify the workspace and response version before using it.

Versioned writes#

Settings changes include the current settings version to prevent overwriting concurrent changes. Read the latest snapshot, send only the intended editable fields, and handle a conflict by refreshing before saving again.

Settings patch body — illustrative version

{
  "version": 3,
  "syncDefaultBranch": true,
  "prCommentsEnabled": true,
  "externalModelsEnabled": false,
  "aiSummaryEnabled": false,
  "retentionDays": 90
}

Only deterministic analysis is available. Retention must be an integer from 7 to 365. Unsupported fields or attempts to enable an unavailable capability are rejected.

Candidate review body — illustrative snapshot

{
  "snapshotId": "<current-snapshot-id>",
  "reviewed": true
}

The review endpoint validates the supplied snapshot against the current evidence. Refresh after a snapshot conflict before recording a new review.

Common response statuses#

Status	Meaning	Next action
400	Invalid input, expired connection flow, or unavailable requested capability.	Read the application error and correct the request or restart connection.
401	Missing, expired, revoked, or otherwise invalid sign-in token.	Sign in again.
403	Insufficient role, unverified identity, inaccessible repository, disallowed account, or missing trusted proxy.	Restore the required authorization and use the website origin.
404	The selected workspace resource is unavailable.	Refresh the authorized selection and verify application IDs.
409	Settings or evidence changed since the request's version/snapshot.	Refresh current data and review before retrying the change.
503	A required application connection or service is unavailable.	Retry after recovery; involve the deployment owner if it persists.