FigChain API Reference

This document provides a comprehensive reference for the FigChain REST API.

Base URL

All endpoints are relative to the API base URL. The base URL of the official FigChain service is https://app.figchain.io/api.

Authentication

Most endpoints require a Bearer Token (JWT) in the Authorization header. Authorization: Bearer <token>

RBAC and Permissions

Endpoints are secured using Role-Based Access Control (RBAC). The required authorities (e.g., MANAGE_USERS, READ_FIGS) are listed for each endpoint.

Authorization

Manage user roles and permissions.

Base Path: /auth

Method	Endpoint	Permissions	Description
`PUT`	`/auth/tenants/{tenantId}/users/{userId}/roles/TENANT_ADMIN`	`MANAGE_TENANTS`	Grant Tenant Admin role to a user.
`DELETE`	`/auth/tenants/{tenantId}/users/{userId}/roles/TENANT_ADMIN`	`MANAGE_TENANTS`	Revoke Tenant Admin role from a user.
`GET`	`/auth/tenants/{tenantId}/users/{userId}/roles`	`MANAGE_USERS`	Get roles for a user in a tenant.
`PUT`	`/auth/tenants/{tenantId}/namespaces/{namespace}/users/{userId}/permissions`	`MANAGE_USERS`	Assign namespace-level permissions (`NAMESPACE_ADMIN`, `NAMESPACE_USER`).
`DELETE`	`/auth/tenants/{tenantId}/namespaces/{namespace}/users/{userId}/permissions`	`MANAGE_USERS`	Remove namespace-level permissions.
`GET`	`/auth/tenants/{tenantId}/namespaces/{namespace}/users`	`READ_USERS`	Get all users and their roles for a specific namespace.
`GET`	`/auth/tenants/{tenantId}/users/{userId}/namespaces`	`READ_USERS`	Get all namespaces and roles assigned to a user.

Build Settings & Variants

Manage build configurations for different languages.

Base Path: /settings / /tenants/{tenantId}/settings

Method	Endpoint	Permissions	Description
`GET`	`/settings/build-variants/{language}`	`READ_BUILD_VARIANTS`	Get build variants for a language (current tenant).
`GET`	`/settings/languages`	`READ_BUILD_VARIANTS`	Get enabled languages for the tenant.
`PUT`	`/settings/languages/{language}`	`MANAGE_BUILD_VARIANTS`	Update language settings (enable/disable).
`PUT`	`/tenants/{tenantId}/settings/build-variants/{language}`	`MANAGE_BUILD_VARIANTS`	Create or update a build variant.
`GET`	`/tenants/{tenantId}/settings/build-variants`	`READ_BUILD_VARIANTS`	List all build variants for a tenant.
`GET`	`/tenants/{tenantId}/settings/build-variants/{language}`	`READ_BUILD_VARIANTS`	List build variants for a specific language.

Build Status

Track the status of artifact builds.

Base Path: /tenants/{tenantId}/schemas/.../builds (Admin/System) OR /schemas/.../builds (User)

Method	Endpoint	Permissions	Description
`GET`	`/tenants/{tenantId}/schemas/{name}/versions/{ver}/builds`	Public*	List builds for a schema version.
`GET`	`/tenants/{tenantId}/schemas/{name}/versions/{ver}/builds/{id}`	Public*	Get details of a specific build.
`GET`	`/tenants/{tenantId}/schemas/{name}/versions/{ver}/builds/{id}/history`	Public*	Get history of a specific build.
`GET`	`/schemas/{name}/versions/{ver}/builds`	Authenticated	List builds for current user's tenant.
`GET`	`/schemas/{name}/versions/{ver}/builds/{id}`	Authenticated	Get details of a specific build for current user's tenant.

*Note: Explicit tenantId paths are typically for system/admin use.

Changelog

Retrieve history of configuration changes.

Base Path: /changelog

Method	Endpoint	Permissions	Description
`GET`	`/changelog/{namespace}/{environmentId}`	Authenticated	Get changelog entries. Supports pagination via `sinceChangeId` and `limit`.

Configuration Data (Figs)

The core configuration data endpoints used by clients and the UI.

Base Path: /data

Method	Endpoint	Permissions	Description
`POST`	`/data/initial`	`READ_FIGS`	Fetch initial configuration state (Snapshot + Changelogs). Supports JSON and Avro.
`POST`	`/data/updates`	`READ_FIGS`*	Fetch configuration updates since a cursor. Supports JSON and Avro. Long-polling supported via `X-Long-Poll-Timeout` header.

Environments

Manage deployment environments (e.g., Prod, Staging).

Base Path: /environments

Method	Endpoint	Permissions	Description
`GET`	`/environments`	`READ_ENVIRONMENTS`	List all environments.
`GET`	`/environments/{id}`	`READ_ENVIRONMENTS`	Get details of a specific environment.
`GET`	`/environments/sandbox`	`READ_ENVIRONMENTS`	Get the implicit Sandbox environment.
`POST`	`/environments`	`MANAGE_ENVIRONMENTS`	Create a new environment.
`PUT`	`/environments/{id}`	`MANAGE_ENVIRONMENTS`	Update an environment.
`DELETE`	`/environments/{id}`	`MANAGE_ENVIRONMENTS`	Delete an environment.

Figs (Management)

Create and manage configuration definitions and values.

Base Path: /figs

Method	Endpoint	Permissions	Description
`PUT`	`/figs/{namespace}/definitions/{key}`	Authenticated	Create or update a Fig Definition.
`GET`	`/figs/{namespace}/definitions/{key}`	Authenticated	Get a Fig Definition.
`GET`	`/figs/{namespace}/definitions`	Authenticated	List Fig Definitions in a namespace.
`POST`	`/figs`	Authenticated	Create a new Fig version (Value).
`GET`	`/figs/by-id/{figId}/{version}`	Authenticated	Get a specific Fig version by ID.
`GET`	`/figs/{namespace}/{key}`	Authenticated	Get history of Fig versions for a key.
`GET`	`/figs/{namespace}/{key}/{version}`	Authenticated	Get a specific Fig version by Key and Version ID.

Namespaces

Manage configuration namespaces.

Base Path: /namespaces

Method	Endpoint	Permissions	Description
`GET`	`/namespaces`	Authenticated	List namespaces the current user has access to.
`GET`	`/namespaces/all`	`MANAGE_NAMESPACES`	List all namespaces in the tenant.
`POST`	`/namespaces`	`MANAGE_NAMESPACES`	Create a new namespace.
`POST`	`/namespaces/assign`	`MANAGE_USERS`	Assign a namespace to a user.

Rollout Policies

Manage progressive delivery rules (Bake times, Traffic splits).

Base Path: /rollout-policies

Method	Endpoint	Permissions	Description
`GET`	`/rollout-policies/namespace/{ns}/environment/{envId}`	`READ_FIGS`	Get Namespace-level rollout policy.
`PUT`	`/rollout-policies/namespace/{ns}/environment/{envId}`	`MANAGE_FIGS`	Set Namespace-level rollout policy.
`GET`	`/rollout-policies/namespace/{ns}/fig/{figId}/environment/{envId}`	`READ_FIGS`	Get Key-level rollout policy override.
`PUT`	`/rollout-policies/namespace/{ns}/fig/{figId}/environment/{envId}`	`MANAGE_FIGS`	Set Key-level rollout policy override.

Schemas

Manage Avro schemas for configurations.

Base Path: /schemas

Method	Endpoint	Permissions	Description
`GET`	`/schemas`	`READ_SCHEMAS`	List schemas.
`POST`	`/schemas`	`MANAGE_SCHEMAS`	Create/Register a new schema.
`GET`	`/schemas/{name}/{version}`	`READ_SCHEMAS`	Get a specific schema version.
`GET`	`/schemas/{name}/{version}/content`	`READ_SCHEMAS`	Get raw schema content (JSON/Text).
`GET`	`/schemas/{name}/current`	`READ_SCHEMAS`	Get the latest version of a schema.
`POST`	`/suggest/schema`	Authenticated	AI-powered schema suggestion from a prompt.

Secrets

Manage secret values.

Base Path: /tenants/{tenantId}/secrets

Method	Endpoint	Permissions	Description
`GET`	`/tenants/{tenantId}/secrets`	`READ_SECRETS`	List secrets.
`GET`	`/tenants/{tenantId}/secrets/{key}`	`READ_SECRETS`*	Get a secret value. Also supports X-Access-Token auth.
`POST`	`/tenants/{tenantId}/secrets`	`MANAGE_SECRETS`	Create or update a secret.
`DELETE`	`/tenants/{tenantId}/secrets/{key}`	`MANAGE_SECRETS`	Delete a secret.
`POST`	`/tenants/{tenantId}/secrets/{key}/token`	`READ_SECRETS`	Issue a short-lived access token for a secret.

Tenants & Settings

Manage tenant-level configuration.

Base Path: /tenants

Method	Endpoint	Permissions	Description
`POST`	`/tenants/{tenantId}/onboard`	`MANAGE_TENANTS`	Trigger onboarding for a new tenant.
`PUT`	`/tenants/name`	`MANAGE_CURRENT_TENANT`	Update current tenant's name.
`PUT`	`/tenants/{tenantId}/name`	`MANAGE_TENANTS`	Update a specific tenant's name (Admin).
`PUT`	`/settings/languages`	`MANAGE_BUILD_VARIANTS`	Bulk update language and build settings.

Users & Authentication

User session management and profiles.

Base Path: /users

Method	Endpoint	Permissions	Description
`POST`	`/users/login`	Public	Login with username/password.
`POST`	`/users/logout`	Public	Logout (clears cookies).
`POST`	`/users/refresh`	Public	Refresh access token.
`POST`	`/users/signin`	Public	Initiate email magic-link sign-in.
`POST`	`/users/signin/{token}`	Public	Complete email magic-link sign-in.
`POST`	`/users/signin/google`	Public	Sign in with Google.
`POST`	`/users/signin/select-tenant`	Authenticated	Select a tenant after multi-tenant login.
`GET`	`/users/me`	Authenticated	Get current user profile.
`PUT`	`/users/me/profile`	Authenticated	Update current user profile.
`POST`	`/users`	`MANAGE_USERS`	Create a new user.
`PUT`	`/users/{username}/role/{role}`	`MANAGE_USERS`	Update a user's role.
`POST`	`/users/{username}/password`	Public	Set password (via token).