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.

Build Status

Track the status of artifact builds.

Base Path: /schemas/.../builds

Method	Endpoint	Permissions	Description
`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.

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.

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.

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.

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.