{ "openapi": "3.1.0", "info": { "title": "Feature flags", "version": "2026-10-08", "description": "Manage feature flags and configuration values with targeting rules, percentage rollouts, experiments, scheduled releases, and approvals. Paths are under `https://api.motor.dev/feature_flags`. Client tokens and Motor event subscriptions are documented separately at `/docs/client_tokens` and `/docs/events`, with their API under `https://api.motor.dev/meta`. Authenticate with `Authorization: Bearer `. Mutating POST requests need an `Idempotency-Key`; configuration changes need the environment's `ETag` in `If-Match`. The feature flags API does not support test mode. Use separate environments for staging and production." }, "servers": [ { "url": "https://api.motor.dev/feature_flags" } ], "security": [ { "SecretKey": [] } ], "tags": [ { "name": "Projects" }, { "name": "Environments" }, { "name": "Flags" }, { "name": "Lifecycle" }, { "name": "Segments" }, { "name": "Configuration" }, { "name": "Credentials" }, { "name": "Evaluation" }, { "name": "Audiences" }, { "name": "Release plans" }, { "name": "Experiments" }, { "name": "Changes" }, { "name": "Configuration as code" }, { "name": "Streams" }, { "name": "OFREP" } ], "paths": { "/projects": { "post": { "operationId": "createProject", "tags": [ "Projects" ], "summary": "Create a project", "description": "Creates a project, which groups environments. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/ResourceKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" } }, "required": [ "key", "name" ], "additionalProperties": false }, "example": { "key": "main", "name": "Main", "description": "The web app" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "main", "name": "Main", "description": "The web app", "environment_count": 0, "version": "1", "created_at": "2026-10-05T00:00:03Z", "updated_at": "2026-10-05T00:00:03Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listProjects", "tags": [ "Projects" ], "summary": "List projects", "description": "Lists the team's projects in a stable order. Credentials: a secret key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Filter by an exact resource key.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectList" }, "example": { "data": [ { "id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "main", "name": "Main", "description": "The web app", "environment_count": 0, "version": "1", "created_at": "2026-10-05T00:00:03Z", "updated_at": "2026-10-05T00:00:03Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/projects/{project_id}": { "get": { "operationId": "getProject", "tags": [ "Projects" ], "summary": "Get a project", "description": "Returns a project. Credentials: a secret key.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "main", "name": "Main", "description": "The web app", "environment_count": 0, "version": "1", "created_at": "2026-10-05T00:00:03Z", "updated_at": "2026-10-05T00:00:03Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateProject", "tags": [ "Projects" ], "summary": "Update a project", "description": "Changes the name or description of a project. Credentials: a secret key.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" } }, "additionalProperties": false }, "example": { "name": "Main app" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" }, "example": { "id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "main", "name": "Main app", "description": "The web app", "environment_count": 0, "version": "2", "created_at": "2026-10-05T00:00:03Z", "updated_at": "2026-10-05T00:00:12Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteProject", "tags": [ "Projects" ], "summary": "Delete a project", "description": "Deletes a project. Delete its environments first. Credentials: a secret key.", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffp_8kXTivFLdeu2mgeL2kTj41", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments": { "post": { "operationId": "createEnvironment", "tags": [ "Environments" ], "summary": "Create an environment", "description": "Creates an environment in a project. Each environment has its own flags, segments, revisions, and credentials. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string" }, "key": { "$ref": "#/components/schemas/ResourceKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "client_access": { "$ref": "#/components/schemas/ClientAccess" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] } }, "required": [ "project_id", "key", "name" ], "additionalProperties": false }, "example": { "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "production", "name": "Production" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" }, "example": { "id": "ffe_UJAs9eZep7hvba6xBh5dvY", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "production", "name": "Production", "description": "", "revision": "1", "client_access": { "publishable_key_ids": [], "allowed_origins": [], "allow_native": false }, "approval_policy": { "required": 0, "reviewer_principal_ids": [], "allow_author": false }, "expires_at": null, "status": "active", "flag_count": 0, "segment_count": 0, "created_at": "2026-10-05T00:00:15Z", "updated_at": "2026-10-05T00:00:15Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listEnvironments", "tags": [ "Environments" ], "summary": "List environments", "description": "Lists the environments that the key can read. Credentials: a secret key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Filter by an exact resource key.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter by project ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentList" }, "example": { "data": [ { "id": "ffe_UJAs9eZep7hvba6xBh5dvY", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "production", "name": "Production", "description": "", "revision": "1", "client_access": { "publishable_key_ids": [], "allowed_origins": [], "allow_native": false }, "approval_policy": { "required": 0, "reviewer_principal_ids": [], "allow_author": false }, "expires_at": null, "status": "active", "flag_count": 0, "segment_count": 0, "created_at": "2026-10-05T00:00:15Z", "updated_at": "2026-10-05T00:00:15Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}": { "get": { "operationId": "getEnvironment", "tags": [ "Environments" ], "summary": "Get an environment", "description": "Returns an environment and its current revision. The `ETag` is the environment's management tag, used in `If-Match` when changing its configuration. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" }, "example": { "id": "ffe_UJAs9eZep7hvba6xBh5dvY", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "production", "name": "Production", "description": "", "revision": "1", "client_access": { "publishable_key_ids": [], "allowed_origins": [], "allow_native": false }, "approval_policy": { "required": 0, "reviewer_principal_ids": [], "allow_author": false }, "expires_at": null, "status": "active", "flag_count": 0, "segment_count": 0, "created_at": "2026-10-05T00:00:15Z", "updated_at": "2026-10-05T00:00:15Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateEnvironment", "tags": [ "Environments" ], "summary": "Update an environment", "description": "Changes the name, description, client access policy, or approval policy. Only a team admin can change the approval policy, and the request must include `X-Change-Comment`. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "client_access": { "$ref": "#/components/schemas/ClientAccess" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "approval_policy": { "$ref": "#/components/schemas/ApprovalPolicy" } }, "additionalProperties": false }, "example": { "description": "Live traffic" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" }, "example": { "id": "ffe_UJAs9eZep7hvba6xBh5dvY", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "production", "name": "Production", "description": "Live traffic", "revision": "2", "client_access": { "publishable_key_ids": [], "allowed_origins": [], "allow_native": false }, "approval_policy": { "required": 0, "reviewer_principal_ids": [], "allow_author": false }, "expires_at": null, "status": "active", "flag_count": 0, "segment_count": 0, "created_at": "2026-10-05T00:00:15Z", "updated_at": "2026-10-05T00:00:24Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteEnvironment", "tags": [ "Environments" ], "summary": "Delete an environment", "description": "Deletes an environment and revokes its credentials. First remove its flags, segments, audiences, and experiments, and stop any running release plans. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffe_3XoQo1f4XSAPiuEVqMZz18", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/flags": { "post": { "operationId": "createFlag", "tags": [ "Flags" ], "summary": "Create a flag", "description": "Creates a flag and publishes a new revision. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagCreate" }, "example": { "key": "checkout", "name": "New checkout", "type": "boolean", "enabled": true, "client_visible": true, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off" }, "rules": [ { "id": "paid", "conditions": [ { "segment": "paid", "op": "in_segment" } ], "serve": { "variation": "on" } } ], "tags": [ "web" ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flag" }, "example": { "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout", "name": "New checkout", "description": "", "type": "boolean", "enabled": true, "client_visible": true, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off" }, "prerequisites": [], "targets": [], "rules": [ { "id": "paid", "conditions": [ { "segment": "paid", "op": "in_segment" } ], "serve": { "variation": "on" } } ], "value_schema": null, "tags": [ "web" ], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false, "revision": "5", "created_at": "2026-10-05T00:00:39Z", "updated_at": "2026-10-05T00:00:39Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listFlags", "tags": [ "Flags" ], "summary": "List flags", "description": "Lists the environment's flags in a stable order, with optional filters. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Filter by an exact resource key.", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "required": false, "description": "Only flags with this tag.", "schema": { "type": "string" } }, { "name": "owner", "in": "query", "required": false, "description": "Filter by the ID of the user or service account that owns the flag.", "schema": { "type": "string" } }, { "name": "purpose", "in": "query", "required": false, "description": "Only flags with this purpose.", "schema": { "type": "string" } }, { "name": "lifecycle", "in": "query", "required": false, "description": "Only flags that are `active`, `expired` (past `expires_at`), `archived`, or `stale` (without evaluations for 30 days).", "schema": { "type": "string", "enum": [ "active", "expired", "archived", "stale" ] } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagList" }, "example": { "data": [ { "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "banner", "name": "Banner text", "description": "", "type": "string", "enabled": true, "client_visible": false, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ], "off_variation": "plain", "fallthrough": { "variation": "plain" }, "prerequisites": [], "targets": [], "rules": [], "value_schema": null, "tags": [], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false, "revision": "6", "created_at": "2026-10-05T00:00:42Z", "updated_at": "2026-10-05T00:00:42Z" }, { "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout", "name": "New checkout", "description": "", "type": "boolean", "enabled": true, "client_visible": true, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off" }, "prerequisites": [], "targets": [], "rules": [ { "id": "paid", "conditions": [ { "segment": "paid", "op": "in_segment" } ], "serve": { "variation": "on" } } ], "value_schema": null, "tags": [ "web" ], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false, "revision": "6", "created_at": "2026-10-05T00:00:39Z", "updated_at": "2026-10-05T00:00:39Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/flags/{flag_id}": { "get": { "operationId": "getFlag", "tags": [ "Flags" ], "summary": "Get a flag", "description": "Returns a flag. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flag" }, "example": { "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout", "name": "New checkout", "description": "", "type": "boolean", "enabled": true, "client_visible": true, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off" }, "prerequisites": [], "targets": [], "rules": [ { "id": "paid", "conditions": [ { "segment": "paid", "op": "in_segment" } ], "serve": { "variation": "on" } } ], "value_schema": null, "tags": [ "web" ], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false, "revision": "6", "created_at": "2026-10-05T00:00:39Z", "updated_at": "2026-10-05T00:00:39Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateFlag", "tags": [ "Flags" ], "summary": "Update a flag", "description": "Changes a flag and publishes a new revision. Omitted fields keep their current values; supplied arrays replace the existing arrays in full. If the environment requires approvals, Motor returns `409 approval_required`. Propose a change set instead. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagUpdate" }, "example": { "description": "The checkout of 2026" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flag" }, "example": { "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout", "name": "New checkout", "description": "The checkout of 2026", "type": "boolean", "enabled": true, "client_visible": true, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off" }, "prerequisites": [], "targets": [], "rules": [ { "id": "paid", "conditions": [ { "segment": "paid", "op": "in_segment" } ], "serve": { "variation": "on" } } ], "value_schema": null, "tags": [ "web" ], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false, "revision": "7", "created_at": "2026-10-05T00:00:39Z", "updated_at": "2026-10-05T00:00:51Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteFlag", "tags": [ "Flags" ], "summary": "Delete a flag", "description": "Deletes an archived flag, provided no other resource depends on it. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/flags/{flag_id}/disable": { "post": { "operationId": "disableFlag", "tags": [ "Flags" ], "summary": "Turn a flag off in an emergency", "description": "Sets `enabled` to false without approvals, and cancels the flag's running release plan. Requires the environment admin role. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "comment" ], "additionalProperties": false }, "example": { "comment": "Incident 42" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Flag" }, "example": { "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "banner", "name": "Banner text", "description": "Retiring", "type": "string", "enabled": false, "client_visible": false, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ], "off_variation": "plain", "fallthrough": { "variation": "plain" }, "prerequisites": [], "targets": [], "rules": [], "value_schema": null, "tags": [], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false, "revision": "21", "created_at": "2026-10-05T00:00:42Z", "updated_at": "2026-10-05T00:08:24Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/flags/{flag_id}/statistics": { "get": { "operationId": "getFlagStatistics", "tags": [ "Lifecycle" ], "summary": "Get a flag's evaluation statistics", "description": "Returns hourly evaluation counts by variation and reason, the last evaluation, and whether counts cover every SDK. Motor keeps counts for 90 days. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Only items at or after this RFC 3339 time.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Only items before this RFC 3339 time.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagStatistics" }, "example": { "flag_key": "checkout", "coverage": "full", "usage_status": "used", "last_evaluated_at": "2026-10-05T00:01:30Z", "total": 44, "error_rate": 0, "buckets": [ { "hour": "2026-10-05T00:00:00Z", "counts": [ { "variation": "on", "reason": "TARGETING_MATCH", "count": 42 }, { "variation": "off", "reason": "DEFAULT", "count": 2 } ] } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/flags/{flag_id}/code_references": { "get": { "operationId": "listCodeReferences", "tags": [ "Lifecycle" ], "summary": "List a flag's code references", "description": "Lists code references from the latest scan of each repository and branch. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeReferenceList" }, "example": { "data": [ { "repository": "acme/web", "branch": "main", "commit": "abcdef1", "path": "src/checkout.ts", "line": 12, "url": "https://github.com/acme/web/blob/abcdef1/src/checkout.ts#L12", "scanned_at": "2026-10-04T00:00:00Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/segments": { "post": { "operationId": "createSegment", "tags": [ "Segments" ], "summary": "Create a segment", "description": "Creates a segment and publishes a new revision. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentCreate" }, "example": { "key": "paid", "name": "Paid plans", "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" }, "example": { "id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "paid", "name": "Paid plans", "description": "", "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ], "revision": "3", "created_at": "2026-10-05T00:00:27Z", "updated_at": "2026-10-05T00:00:27Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listSegments", "tags": [ "Segments" ], "summary": "List segments", "description": "Lists the environment's segments in a stable order. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "key", "in": "query", "required": false, "description": "Filter by an exact resource key.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentList" }, "example": { "data": [ { "id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "paid", "name": "Paid plans", "description": "", "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ], "revision": "3", "created_at": "2026-10-05T00:00:27Z", "updated_at": "2026-10-05T00:00:27Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/segments/{segment_id}": { "get": { "operationId": "getSegment", "tags": [ "Segments" ], "summary": "Get a segment", "description": "Returns a segment. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" }, "example": { "id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "paid", "name": "Paid plans", "description": "", "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ], "revision": "3", "created_at": "2026-10-05T00:00:27Z", "updated_at": "2026-10-05T00:00:27Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateSegment", "tags": [ "Segments" ], "summary": "Update a segment", "description": "Changes a segment and publishes a new revision. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentUpdate" }, "example": { "name": "Paid accounts" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Segment" }, "example": { "id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "paid", "name": "Paid accounts", "description": "", "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ], "revision": "4", "created_at": "2026-10-05T00:00:27Z", "updated_at": "2026-10-05T00:00:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteSegment", "tags": [ "Segments" ], "summary": "Delete a segment", "description": "Deletes a segment that no flag uses. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" }, { "$ref": "#/components/parameters/ChangeComment" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffs_RveuKXV25H2KaWKDeUbayF", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/config": { "get": { "operationId": "getConfiguration", "tags": [ "Configuration" ], "summary": "Get the configuration snapshot", "description": "Returns the complete configuration for local evaluation: flags, segments, pinned audiences, experiments, and strategies. A request with the current tag in `If-None-Match` gets `304`. Authentication and rate limits come first, so a revoked credential never gets `304`. Credentials: a secret key, a server SDK key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Configuration" }, "example": { "audiences": [], "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "experiments": [], "flags": [ { "client_visible": false, "enabled": true, "fallthrough": { "variation": "plain" }, "key": "banner", "off_variation": "plain", "prerequisites": [], "rules": [], "targets": [], "type": "string", "value_schema": null, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ] }, { "client_visible": true, "enabled": true, "fallthrough": { "variation": "off" }, "key": "checkout", "off_variation": "off", "prerequisites": [], "rules": [ { "conditions": [ { "op": "in_segment", "segment": "paid" } ], "id": "paid", "serve": { "variation": "on" } } ], "targets": [], "type": "boolean", "value_schema": null, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ] } ], "hash_algorithm": "motor_sha256_v1", "revision": "7", "schema_version": 1, "segments": [ { "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ], "key": "paid" } ], "strategies": [] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "304": { "$ref": "#/components/responses/NotModified" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] } ] } }, "/environments/{environment_id}/revisions": { "get": { "operationId": "listRevisions", "tags": [ "Configuration" ], "summary": "List revisions", "description": "Lists retained revisions, newest first. Motor retains the current revision and up to 99 previous revisions from the last 90 days. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionMetadataList" }, "example": { "data": [ { "revision": "7", "created_at": "2026-10-05T00:00:51Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.flag.updated", "comment": null, "restored_from": null }, { "revision": "6", "created_at": "2026-10-05T00:00:42Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.flag.created", "comment": null, "restored_from": null }, { "revision": "5", "created_at": "2026-10-05T00:00:39Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.flag.created", "comment": null, "restored_from": null }, { "revision": "4", "created_at": "2026-10-05T00:00:36Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.segment.updated", "comment": null, "restored_from": null }, { "revision": "3", "created_at": "2026-10-05T00:00:27Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.segment.created", "comment": null, "restored_from": null }, { "revision": "2", "created_at": "2026-10-05T00:00:24Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.environment.updated", "comment": null, "restored_from": null }, { "revision": "1", "created_at": "2026-10-05T00:00:15Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.environment.created", "comment": null, "restored_from": null } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/revisions/{revision}": { "get": { "operationId": "getRevision", "tags": [ "Configuration" ], "summary": "Get a revision", "description": "Returns a revision's metadata and its management snapshot. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevisionSnapshot" }, "example": { "revision": "1", "created_at": "2026-10-05T00:00:15Z", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "action": "feature_flags.environment.created", "comment": null, "restored_from": null, "snapshot": { "approval_policy": { "allow_author": false, "required": 0, "reviewer_principal_ids": [] }, "audiences": [], "client_access": { "allow_native": false, "allowed_origins": [], "publishable_key_ids": [] }, "environment": { "description": "", "id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "production", "name": "Production", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45" }, "experiments": [], "flags": [], "format": "motor.feature_flags.management", "revision": "1", "schema_version": 1, "segments": [] } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/rollback": { "post": { "operationId": "rollBack", "tags": [ "Configuration" ], "summary": "Roll back", "description": "Restores all flags and segments from a retained revision and publishes them as a new revision. It doesn't restore policies or credentials. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "$ref": "#/components/schemas/Revision" }, "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "revision", "comment" ], "additionalProperties": false }, "example": { "revision": "7", "comment": "Undo the description" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" }, "example": { "id": "ffe_UJAs9eZep7hvba6xBh5dvY", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "production", "name": "Production", "description": "Live traffic", "revision": "9", "client_access": { "publishable_key_ids": [], "allowed_origins": [], "allow_native": false }, "approval_policy": { "required": 0, "reviewer_principal_ids": [], "allow_author": false }, "expires_at": null, "status": "active", "flag_count": 2, "segment_count": 1, "created_at": "2026-10-05T00:00:15Z", "updated_at": "2026-10-05T00:01:06Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/audit_events": { "get": { "operationId": "listAuditEvents", "tags": [ "Configuration" ], "summary": "List audit events", "description": "Lists audit events accessible to the key, newest first. Motor retains up to 10,000 audit events per team from the last 90 days. Credentials: a secret key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "environment_id", "in": "query", "required": false, "description": "Only this environment.", "schema": { "type": "string" } }, { "name": "resource_id", "in": "query", "required": false, "description": "Only events of this resource.", "schema": { "type": "string" } }, { "name": "action", "in": "query", "required": false, "description": "Only events of this action, such as `feature_flags.flag.updated`.", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "Only items at or after this RFC 3339 time.", "schema": { "type": "string" } }, { "name": "before", "in": "query", "required": false, "description": "Only items before this RFC 3339 time.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventList" }, "example": { "data": [ { "id": "ffa_0_11", "sequence": "11", "at": "2026-10-05T00:01:06Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "environment", "resource_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "resource_key": "production", "action": "feature_flags.environment.rolled_back", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "8", "revision_after": "9", "comment": "Undo the description", "changed_fields": [ "flags" ], "before_digest": "ff43e147d64a87069d2164f61f614ab179c40d3f1e1587fd8bffadb09e51a502", "after_digest": "63700af2c114a8f6a92285299408f0548e4355208536ad3c2832a0c7deea3d84" }, { "id": "ffa_0_10", "sequence": "10", "at": "2026-10-05T00:01:03Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "flag", "resource_id": "ffl_VrfGhkyrB2pjGqESka3ALF", "resource_key": "checkout", "action": "feature_flags.flag.updated", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "7", "revision_after": "8", "comment": null, "changed_fields": [ "description" ], "before_digest": "c10534a1e1c5c5c5250dba52a2fad84b2cf120b4ef0611aa58e70939d0803ecf", "after_digest": "31588d37159b234cbded0bee17bc9e24687bde8b7338a0582c889b5c62a85ed5" }, { "id": "ffa_0_9", "sequence": "9", "at": "2026-10-05T00:00:51Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "flag", "resource_id": "ffl_VrfGhkyrB2pjGqESka3ALF", "resource_key": "checkout", "action": "feature_flags.flag.updated", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "6", "revision_after": "7", "comment": null, "changed_fields": [ "description" ], "before_digest": "a33ebc0aeb309ccb3d455b266f61b75357ec6df48802e0d20f37b5f02682c9e4", "after_digest": "c10534a1e1c5c5c5250dba52a2fad84b2cf120b4ef0611aa58e70939d0803ecf" }, { "id": "ffa_0_8", "sequence": "8", "at": "2026-10-05T00:00:42Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "flag", "resource_id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "resource_key": "banner", "action": "feature_flags.flag.created", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "5", "revision_after": "6", "comment": null, "changed_fields": [ "archived", "client_visible", "created_at", "description", "enabled", "expires_at", "fallthrough", "id", "key", "name", "off_variation", "owner_principal_id", "prerequisites", "purpose", "rules", "tags", "targets", "type", "value_schema", "variations" ], "before_digest": null, "after_digest": "af63e352aff6bca9a785ae26388ec7bbf5166ad2e1904670cd7c666bbd499477" }, { "id": "ffa_0_7", "sequence": "7", "at": "2026-10-05T00:00:39Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "flag", "resource_id": "ffl_VrfGhkyrB2pjGqESka3ALF", "resource_key": "checkout", "action": "feature_flags.flag.created", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "4", "revision_after": "5", "comment": null, "changed_fields": [ "archived", "client_visible", "created_at", "description", "enabled", "expires_at", "fallthrough", "id", "key", "name", "off_variation", "owner_principal_id", "prerequisites", "purpose", "rules", "tags", "targets", "type", "value_schema", "variations" ], "before_digest": null, "after_digest": "a33ebc0aeb309ccb3d455b266f61b75357ec6df48802e0d20f37b5f02682c9e4" }, { "id": "ffa_0_6", "sequence": "6", "at": "2026-10-05T00:00:36Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "segment", "resource_id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "resource_key": "paid", "action": "feature_flags.segment.updated", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "3", "revision_after": "4", "comment": null, "changed_fields": [ "name" ], "before_digest": "3f9e06e491819cdcb1994c1441ba386066b687987b606cf0479f905bfd120dcf", "after_digest": "4a4b2bd015c7c8de4016b4eecf92ab86d007a548837f7671a0a7a9e23598fa7d" }, { "id": "ffa_0_5", "sequence": "5", "at": "2026-10-05T00:00:27Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "segment", "resource_id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "resource_key": "paid", "action": "feature_flags.segment.created", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "2", "revision_after": "3", "comment": null, "changed_fields": [ "created_at", "description", "groups", "id", "key", "name" ], "before_digest": null, "after_digest": "3f9e06e491819cdcb1994c1441ba386066b687987b606cf0479f905bfd120dcf" }, { "id": "ffa_0_4", "sequence": "4", "at": "2026-10-05T00:00:24Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "environment", "resource_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "resource_key": "production", "action": "feature_flags.environment.updated", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": "1", "revision_after": "2", "comment": null, "changed_fields": [ "description" ], "before_digest": "9b7383a7ad0c93c22a5be55e20a068d9e9262f51f277042107afece86e33aa52", "after_digest": "1cd45c0fcd98c2a04681905f554cd54960e90f756c2e2903bf42055a62d0d3fe" }, { "id": "ffa_0_3", "sequence": "3", "at": "2026-10-05T00:00:15Z", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "environment_key": "production", "resource_type": "environment", "resource_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "resource_key": "production", "action": "feature_flags.environment.created", "actor_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "actor_name": "Agent", "principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "revision_before": null, "revision_after": "1", "comment": null, "changed_fields": [ "key", "name" ], "before_digest": null, "after_digest": "e4c08c5a73f5be63488a322b2d202bd37d2ec411ea634797ff83fbf32ca9e908" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/sdk_keys": { "post": { "operationId": "createSdkKey", "tags": [ "Credentials" ], "summary": "Create a server SDK key", "description": "Creates a key that reads one environment's configuration and evaluates its flags. The response shows the secret once; an idempotent retry recovers the same secret. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Web servers" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkKeySecret" }, "example": { "id": "ffk_6b4EGwzwbss1Gf5WBQaXGa", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Web servers", "owner_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "created_at": "2026-10-05T00:01:12Z", "revoked_at": null, "secret": "motor_ffsk_EXAMPLE_NOT_A_REAL_SECRET" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listSdkKeys", "tags": [ "Credentials" ], "summary": "List server SDK keys", "description": "Lists an environment's SDK keys, without secrets. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkKeyList" }, "example": { "data": [ { "id": "ffk_6b4EGwzwbss1Gf5WBQaXGa", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Web servers", "owner_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "created_at": "2026-10-05T00:01:12Z", "revoked_at": null } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/sdk_keys/{sdk_key_id}": { "delete": { "operationId": "revokeSdkKey", "tags": [ "Credentials" ], "summary": "Revoke a server SDK key", "description": "Immediately revokes the key and closes its event streams. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "sdk_key_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffk_6b4EGwzwbss1Gf5WBQaXGa", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/limits": { "get": { "operationId": "getLimits", "tags": [ "Credentials" ], "summary": "Get limits", "description": "Returns the resource limits currently applied to the team, project, or environment. Contact Motor support to request an increase. Credentials: a secret key.", "parameters": [ { "name": "project_id", "in": "query", "required": false, "description": "Filter by project ID.", "schema": { "type": "string" } }, { "name": "environment_id", "in": "query", "required": false, "description": "Only this environment.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Limits" }, "example": { "configuration_version": "0", "data": [ { "key": "max_flags", "description": "Flags of one environment.", "scope": "flag_environment", "scope_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "unit": "flags", "default": 5000, "effective": 5000 }, { "key": "max_segments", "description": "Segments of one environment.", "scope": "flag_environment", "scope_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "unit": "segments", "default": 1000, "effective": 1000 }, { "key": "max_running_experiments", "description": "Running experiments of one environment.", "scope": "flag_environment", "scope_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "unit": "experiments", "default": 100, "effective": 100 } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/access_policy": { "get": { "operationId": "getAccessPolicy", "tags": [ "Credentials" ], "summary": "Get the access policy", "description": "Returns the roles assigned to users and service accounts in the team. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPolicy" }, "example": { "version": "1", "grants": [], "default_role": "editor", "updated_at": "1970-01-01T00:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateAccessPolicy", "tags": [ "Credentials" ], "summary": "Update the access policy", "description": "Replaces the team's role assignments. Requires a team admin's secret key. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "principal_id": { "type": "string" }, "project_ids": { "type": "array", "items": { "type": "string" } }, "environment_ids": { "type": "array", "items": { "type": "string" } }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "reader", "evaluator", "editor", "reviewer", "admin" ] }, "minItems": 1 } }, "required": [ "principal_id", "roles" ], "additionalProperties": false } }, "default_role": { "type": "string", "enum": [ "none", "editor" ] } }, "additionalProperties": false }, "example": { "grants": [ { "principal_id": "user_CbJvbgw5XNiJcPMi9mEavM", "project_ids": [], "environment_ids": [], "roles": [ "reviewer", "editor" ] } ], "default_role": "none" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessPolicy" }, "example": { "version": "2", "grants": [ { "principal_id": "user_CbJvbgw5XNiJcPMi9mEavM", "project_ids": [], "environment_ids": [], "roles": [ "reviewer", "editor" ] } ], "default_role": "none", "updated_at": "2026-10-05T00:01:24Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/evaluations": { "post": { "operationId": "evaluate", "tags": [ "Evaluation" ], "summary": "Evaluate flags", "description": "Evaluates 1 to 100 flags for one context. Each accepted request is billed as one remote evaluation ($0.03 per 1,000 requests), regardless of the number of flags or their results. Don't retry automatically: a retry is another billable request. Credentials: a secret key, a server SDK key, a publishable key, a client token.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "environment_id": { "type": "string" }, "context": { "$ref": "#/components/schemas/Context" }, "flags": { "type": "array", "items": { "$ref": "#/components/schemas/Wanted" }, "minItems": 1, "maxItems": 100 }, "strategy_results": { "type": "object", "description": "Trusted results of custom strategies, such as `{\"my_strategy@1\": true}`. Secret and SDK keys only.", "additionalProperties": { "type": "boolean" } }, "record_exposure": { "type": "boolean", "description": "Whether an experiment result records an exposure. Default true; use false for prefetch." } }, "required": [ "environment_id", "flags" ], "additionalProperties": false }, "example": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "context": { "targeting_key": "user_123", "attributes": { "plan": "pro" } }, "flags": [ { "key": "checkout", "type": "boolean", "default": false }, { "key": "banner", "type": "string", "default": "Welcome" } ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluationResults" }, "example": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "revision": "10", "results": [ { "key": "checkout", "value": true, "variation": "on", "reason": "TARGETING_MATCH", "rule_id": "paid", "prerequisite_key": null, "error_code": null, "experiment": null }, { "key": "banner", "value": "Welcome", "variation": "plain", "reason": "DEFAULT", "rule_id": null, "prerequisite_key": null, "error_code": null, "experiment": null } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "PublishableKey": [] }, { "ClientToken": [] } ] } }, "/environments/{environment_id}/evaluation_counts": { "post": { "operationId": "reportEvaluationCounts", "tags": [ "Lifecycle" ], "summary": "Report evaluation counts", "description": "Reports aggregate local evaluation counts for an interval of up to one hour. Reports are not billed. Resending the same batch ID and counts does not add to the totals. Credentials: a secret key, a server SDK key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batch_id": { "type": "string", "minLength": 1, "maxLength": 128 }, "interval_start": { "$ref": "#/components/schemas/Time" }, "interval_end": { "$ref": "#/components/schemas/Time" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "flag_key": { "$ref": "#/components/schemas/FlagKey" }, "variation": { "type": [ "string", "null" ] }, "reason": { "type": "string" }, "count": { "type": "integer", "minimum": 1 } }, "required": [ "flag_key", "reason", "count" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "batch_id", "interval_start", "interval_end", "counts" ], "additionalProperties": false }, "example": { "batch_id": "b1", "interval_start": "2026-10-05T00:00:00Z", "interval_end": "2026-10-05T00:01:00Z", "counts": [ { "flag_key": "checkout", "variation": "on", "reason": "TARGETING_MATCH", "count": 40 } ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountReport" }, "example": { "batch_id": "b1", "accepted": true, "duplicate": false } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] } ] } }, "/environments/{environment_id}/dependency_graph": { "get": { "operationId": "getDependencyGraph", "tags": [ "Lifecycle" ], "summary": "Get the dependency graph", "description": "Returns the prerequisites, segments, audiences, experiments, and release plans that flags use. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DependencyGraph" }, "example": { "revision": "10", "nodes": [ { "type": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner" }, { "type": "flag", "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "key": "checkout" }, { "type": "segment", "id": "ffs_VNaTX9Ts3sbY1UXdfYmL8g", "key": "paid" } ], "edges": [ { "from": "flag:checkout", "to": "segment:paid", "kind": "segment" } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/evaluation_preview": { "post": { "operationId": "previewEvaluation", "tags": [ "Lifecycle" ], "summary": "Preview an evaluation", "description": "Evaluates flags and returns a trace explaining each decision. Previews are not billed and do not create assignments or exposures. Omit the idempotency key. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "revision": { "$ref": "#/components/schemas/Revision" }, "context": { "$ref": "#/components/schemas/Context" }, "flags": { "type": "array", "items": { "$ref": "#/components/schemas/Wanted" }, "minItems": 1, "maxItems": 100 }, "trace": { "type": "boolean" } }, "required": [ "flags" ], "additionalProperties": false }, "example": { "context": { "targeting_key": "user_123", "attributes": { "plan": "pro" } }, "flags": [ { "key": "checkout", "type": "boolean", "default": false } ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" }, "example": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "results": [ { "key": "checkout", "value": true, "variation": "on", "reason": "TARGETING_MATCH", "rule_id": "paid", "prerequisite_key": null, "error_code": null, "experiment": null } ], "trace": [ { "step": "flag", "flag_key": "checkout" }, { "step": "rule", "rule_id": "paid", "matched": true } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/code_references": { "post": { "operationId": "reportCodeReferences", "tags": [ "Lifecycle" ], "summary": "Report code references", "description": "Replaces the code references for one repository and branch with the supplied scan results. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "repository": { "type": "string", "minLength": 1, "maxLength": 256 }, "branch": { "type": "string", "minLength": 1, "maxLength": 256 }, "commit": { "type": "string", "minLength": 1, "maxLength": 64 }, "scanned_at": { "$ref": "#/components/schemas/Time" }, "references": { "type": "array", "items": { "type": "object", "properties": { "flag_key": { "$ref": "#/components/schemas/FlagKey" }, "path": { "type": "string" }, "line": { "type": "integer", "minimum": 1 }, "url": { "type": "string" } }, "required": [ "flag_key", "path", "line" ], "additionalProperties": false }, "minItems": 0, "maxItems": 10000 } }, "required": [ "repository", "branch", "commit", "scanned_at", "references" ], "additionalProperties": false }, "example": { "repository": "acme/web", "branch": "main", "commit": "abcdef1", "scanned_at": "2026-10-04T00:00:00Z", "references": [ { "flag_key": "checkout", "path": "src/checkout.ts", "line": 12, "url": "https://github.com/acme/web/blob/abcdef1/src/checkout.ts#L12" } ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CodeReferenceReport" }, "example": { "repository": "acme/web", "branch": "main", "commit": "abcdef1", "scanned_at": "2026-10-04T00:00:00Z", "reference_count": 1 } } } }, "401": { "$ref": "#/components/responses/Error401" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/audiences": { "post": { "operationId": "createAudience", "tags": [ "Audiences" ], "summary": "Create an audience", "description": "Creates an imported audience, a list of up to 1,000,000 targeting keys that rules can use. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "match_by": { "type": "string", "enum": [ "targeting_key" ] }, "local_delivery": { "type": "boolean", "description": "Whether server SDKs get the membership chunks. Default true." } }, "required": [ "key", "name" ], "additionalProperties": false }, "example": { "key": "beta", "name": "Beta testers" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" }, "example": { "id": "ffauds_EsdpMBV91zRKnBddyK2dux", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "beta", "name": "Beta testers", "description": "", "match_by": "targeting_key", "local_delivery": true, "committed_version": null, "version": "1", "created_at": "2026-10-05T00:02:03Z", "updated_at": "2026-10-05T00:02:03Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listAudiences", "tags": [ "Audiences" ], "summary": "List audiences", "description": "Lists the environment's audiences. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceList" }, "example": { "data": [ { "id": "ffauds_EsdpMBV91zRKnBddyK2dux", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "beta", "name": "Beta testers", "description": "", "match_by": "targeting_key", "local_delivery": true, "committed_version": null, "version": "1", "created_at": "2026-10-05T00:02:03Z", "updated_at": "2026-10-05T00:02:03Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/audiences/{audience_id}": { "get": { "operationId": "getAudience", "tags": [ "Audiences" ], "summary": "Get an audience", "description": "Returns an audience and its current version. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" }, "example": { "id": "ffauds_EsdpMBV91zRKnBddyK2dux", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "beta", "name": "Beta testers", "description": "", "match_by": "targeting_key", "local_delivery": true, "committed_version": null, "version": "1", "created_at": "2026-10-05T00:02:03Z", "updated_at": "2026-10-05T00:02:03Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateAudience", "tags": [ "Audiences" ], "summary": "Update an audience", "description": "Changes an audience's name, description, or availability for local evaluation. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "local_delivery": { "type": "boolean" } }, "additionalProperties": false }, "example": { "name": "Beta users" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" }, "example": { "id": "ffauds_EsdpMBV91zRKnBddyK2dux", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "beta", "name": "Beta users", "description": "", "match_by": "targeting_key", "local_delivery": true, "committed_version": null, "version": "2", "created_at": "2026-10-05T00:02:03Z", "updated_at": "2026-10-05T00:02:12Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteAudience", "tags": [ "Audiences" ], "summary": "Delete an audience", "description": "Deletes an audience that no flag or segment uses. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffauds_HYghvt78rohy83YCEmzdYP", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/audiences/{audience_id}/imports": { "post": { "operationId": "uploadAudienceMembers", "tags": [ "Audiences" ], "summary": "Upload audience members", "description": "Uploads newline-delimited targeting keys (at most 64 MiB). A job checks and stages them; nothing changes until you commit the import. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "text/plain": { "schema": { "type": "string", "description": "UTF-8 text: one targeting key of 1 to 256 bytes on each line." }, "example": "user_1\nuser_2\n" } } }, "responses": { "202": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceImport" }, "example": { "id": "ffaudi_TchiqWGh3FyaanRo5hAvXa", "audience_id": "ffauds_EsdpMBV91zRKnBddyK2dux", "status": "processing", "members": 0, "duplicates": 0, "digest": null, "chunk_count": 0, "errors": [], "version": null, "created_at": "2026-10-05T00:02:12Z", "finished_at": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/audiences/{audience_id}/imports/{import_id}": { "get": { "operationId": "getAudienceImport", "tags": [ "Audiences" ], "summary": "Get an audience import", "description": "Returns an import's status: `processing`, `ready`, or `failed`. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "import_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceImport" }, "example": { "id": "ffaudi_TchiqWGh3FyaanRo5hAvXa", "audience_id": "ffauds_EsdpMBV91zRKnBddyK2dux", "status": "ready", "members": 2, "duplicates": 0, "digest": "0ff5263c14f3e95f4e6f53891bacb664a4f3f5d35b2efe68ee75a0df5143b950", "chunk_count": 1, "errors": [], "version": null, "created_at": "2026-10-05T00:02:12Z", "finished_at": "2026-10-08T16:30:47Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/audiences/{audience_id}/imports/{import_id}/commit": { "post": { "operationId": "commitAudienceImport", "tags": [ "Audiences" ], "summary": "Commit an audience import", "description": "Makes a ready import the audience's current version, and publishes a new revision. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "import_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_revision": { "$ref": "#/components/schemas/Revision" } }, "required": [ "base_revision" ], "additionalProperties": false }, "example": { "base_revision": "10" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" }, "example": { "id": "ffaudi_TchiqWGh3FyaanRo5hAvXa", "audience_id": "ffauds_EsdpMBV91zRKnBddyK2dux", "status": "committed", "members": 2, "duplicates": 0, "digest": "0ff5263c14f3e95f4e6f53891bacb664a4f3f5d35b2efe68ee75a0df5143b950", "chunk_count": 1, "errors": [], "version": "1", "created_at": "2026-10-05T00:02:12Z", "finished_at": "2026-10-08T16:30:47Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/audiences/{audience_id}/versions/{version}/chunks/{index}": { "get": { "operationId": "getAudienceChunk", "tags": [ "Audiences" ], "summary": "Get an audience chunk", "description": "Returns one immutable chunk of 4,096 sorted SHA-256 membership hashes, for server SDKs. Credentials: a secret key, a server SDK key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "audience_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "index", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceChunk" }, "example": { "audience_id": "ffauds_EsdpMBV91zRKnBddyK2dux", "format": "motor.feature_flags.audience_chunk", "hashes": [ "36372583505716e7f086f04d84b818c9cbd77c36b6b47aeed9403d306c76ced7", "402ad881fde87d9f270a1e0e1cc833fc7b295e6bf235637e211f364c14215a80" ], "index": 0 } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] } ] } }, "/environments/{environment_id}/release_plans": { "post": { "operationId": "createReleasePlan", "tags": [ "Release plans" ], "summary": "Create a release plan", "description": "Schedules a sequence of configuration changes, either directly or from a template with a `start_at` time. Each step publishes a new revision. If its expected base revision has changed, the step fails with a revision conflict. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "base_revision": { "$ref": "#/components/schemas/Revision" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "at": { "$ref": "#/components/schemas/Time" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "at", "operations" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "metric_id": { "type": "string" }, "comparison": { "type": "string", "enum": [ "treatment_vs_control", "absolute" ] }, "max_increase": { "type": "number" }, "minimum_exposures": { "type": "integer", "minimum": 1 }, "window_seconds": { "type": "integer", "minimum": 60 }, "action": { "type": "string", "enum": [ "pause", "rollback" ] } }, "required": [ "metric_id", "max_increase" ], "additionalProperties": false }, "minItems": 0, "maxItems": 10 }, "comment": { "$ref": "#/components/schemas/Comment" }, "template_id": { "type": "string" }, "start_at": { "$ref": "#/components/schemas/Time" } }, "required": [ "name", "base_revision" ], "additionalProperties": false }, "example": { "name": "Checkout launch", "base_revision": "11", "comment": "10% then 50%", "steps": [ { "at": "2026-10-05T01:00:00Z", "operations": [ { "op": "update", "resource": "flag", "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "body": { "fallthrough": { "rollout": { "seed": "launch", "bucket_by": "targeting_key", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } } } ] }, { "at": "2026-10-05T02:00:00Z", "operations": [ { "op": "update", "resource": "flag", "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "body": { "fallthrough": { "rollout": { "seed": "launch", "bucket_by": "targeting_key", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } } } ] } ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePlan" }, "example": { "id": "ffrp_3UCS21dyKxZGTC8yd917i8", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Checkout launch", "base_revision": "11", "steps": [ { "at": "2026-10-05T01:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] }, { "at": "2026-10-05T02:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "comment": "10% then 50%", "status": "scheduled", "change_id": null, "next_step": 0, "applied_steps": [], "history": [], "version": "1", "created_at": "2026-10-05T00:02:36Z", "updated_at": "2026-10-05T00:02:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listReleasePlans", "tags": [ "Release plans" ], "summary": "List release plans", "description": "Lists the environment's release plans in a stable order. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePlanList" }, "example": { "data": [ { "id": "ffrp_3UCS21dyKxZGTC8yd917i8", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Checkout launch", "base_revision": "11", "steps": [ { "at": "2026-10-05T01:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] }, { "at": "2026-10-05T02:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "comment": "10% then 50%", "status": "scheduled", "change_id": null, "next_step": 0, "applied_steps": [], "history": [], "version": "1", "created_at": "2026-10-05T00:02:36Z", "updated_at": "2026-10-05T00:02:36Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/release_plans/{plan_id}": { "get": { "operationId": "getReleasePlan", "tags": [ "Release plans" ], "summary": "Get a release plan", "description": "Returns a release plan, including its steps and which steps have been applied. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePlan" }, "example": { "id": "ffrp_3UCS21dyKxZGTC8yd917i8", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Checkout launch", "base_revision": "11", "steps": [ { "at": "2026-10-05T01:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] }, { "at": "2026-10-05T02:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "comment": "10% then 50%", "status": "scheduled", "change_id": null, "next_step": 0, "applied_steps": [], "history": [], "version": "1", "created_at": "2026-10-05T00:02:36Z", "updated_at": "2026-10-05T00:02:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/release_plans/{plan_id}/pause": { "post": { "operationId": "pauseReleasePlan", "tags": [ "Release plans" ], "summary": "Pause a release plan", "description": "Pauses a running plan. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } }, "additionalProperties": false }, "example": { "comment": "Wait for support" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePlan" }, "example": { "id": "ffrp_3UCS21dyKxZGTC8yd917i8", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Checkout launch", "base_revision": "11", "steps": [ { "at": "2026-10-05T01:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] }, { "at": "2026-10-05T02:00:00Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "comment": "10% then 50%", "status": "paused", "change_id": null, "next_step": 0, "applied_steps": [], "history": [], "version": "2", "created_at": "2026-10-05T00:02:36Z", "updated_at": "2026-10-05T00:02:45Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/release_plans/{plan_id}/resume": { "post": { "operationId": "resumeReleasePlan", "tags": [ "Release plans" ], "summary": "Resume a release plan", "description": "Resumes a paused plan. Overdue steps are applied in order. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } }, "additionalProperties": false }, "example": { "comment": "Ready" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePlan" }, "example": { "id": "ffrp_3UCS21dyKxZGTC8yd917i8", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Checkout launch", "base_revision": "11", "steps": [ { "at": "2026-10-05T01:00:03Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] }, { "at": "2026-10-05T02:00:03Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "comment": "10% then 50%", "status": "scheduled", "change_id": null, "next_step": 0, "applied_steps": [], "history": [], "version": "3", "created_at": "2026-10-05T00:02:36Z", "updated_at": "2026-10-05T00:02:48Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/release_plans/{plan_id}/cancel": { "post": { "operationId": "cancelReleasePlan", "tags": [ "Release plans" ], "summary": "Cancel a release plan", "description": "Cancels a release plan. Changes from steps already applied remain in effect. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "plan_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } }, "additionalProperties": false }, "example": { "comment": "Not now" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleasePlan" }, "example": { "id": "ffrp_3UCS21dyKxZGTC8yd917i8", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "name": "Checkout launch", "base_revision": "11", "steps": [ { "at": "2026-10-05T01:00:03Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 10000 }, { "variation": "off", "weight": 90000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] }, { "at": "2026-10-05T02:00:03Z", "operations": [ { "body": { "fallthrough": { "rollout": { "bucket_by": "targeting_key", "seed": "launch", "weights": [ { "variation": "on", "weight": 50000 }, { "variation": "off", "weight": 50000 } ] } } }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "comment": "10% then 50%", "status": "canceled", "change_id": null, "next_step": 0, "applied_steps": [], "history": [], "version": "4", "created_at": "2026-10-05T00:02:36Z", "updated_at": "2026-10-05T00:02:51Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/release_templates": { "post": { "operationId": "createReleaseTemplate", "tags": [ "Release plans" ], "summary": "Create a release template", "description": "Creates a reusable template of steps relative to a start time. Credentials: a secret key.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string" }, "key": { "$ref": "#/components/schemas/ResourceKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "after_seconds": { "type": "integer", "minimum": 0 }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "after_seconds", "operations" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "metric_id": { "type": "string" }, "comparison": { "type": "string", "enum": [ "treatment_vs_control", "absolute" ] }, "max_increase": { "type": "number" }, "minimum_exposures": { "type": "integer", "minimum": 1 }, "window_seconds": { "type": "integer", "minimum": 60 }, "action": { "type": "string", "enum": [ "pause", "rollback" ] } }, "required": [ "metric_id", "max_increase" ], "additionalProperties": false }, "minItems": 0, "maxItems": 10 } }, "required": [ "project_id", "key", "name", "steps" ], "additionalProperties": false }, "example": { "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "gradual", "name": "Gradual", "steps": [ { "after_seconds": 3600, "operations": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "body": { "description": "Step one" } } ] } ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseTemplate" }, "example": { "id": "ffrt_858vymcGFLBztDgAtMihee", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "gradual", "name": "Gradual", "description": "", "steps": [ { "after_seconds": 3600, "operations": [ { "body": { "description": "Step one" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "version": "1", "created_at": "2026-10-05T00:02:24Z", "updated_at": "2026-10-05T00:02:24Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listReleaseTemplates", "tags": [ "Release plans" ], "summary": "List release templates", "description": "Lists the team's templates. Credentials: a secret key.", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "project_id", "in": "query", "required": false, "description": "Filter by project ID.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseTemplateList" }, "example": { "data": [ { "id": "ffrt_858vymcGFLBztDgAtMihee", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "gradual", "name": "Gradual", "description": "", "steps": [ { "after_seconds": 3600, "operations": [ { "body": { "description": "Step one" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "version": "1", "created_at": "2026-10-05T00:02:24Z", "updated_at": "2026-10-05T00:02:24Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/release_templates/{template_id}": { "get": { "operationId": "getReleaseTemplate", "tags": [ "Release plans" ], "summary": "Get a release template", "description": "Returns a template. Credentials: a secret key.", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseTemplate" }, "example": { "id": "ffrt_858vymcGFLBztDgAtMihee", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "gradual", "name": "Gradual", "description": "", "steps": [ { "after_seconds": 3600, "operations": [ { "body": { "description": "Step one" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "version": "1", "created_at": "2026-10-05T00:02:24Z", "updated_at": "2026-10-05T00:02:24Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateReleaseTemplate", "tags": [ "Release plans" ], "summary": "Update a release template", "description": "Changes a template. Credentials: a secret key.", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "after_seconds": { "type": "integer", "minimum": 0 }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "after_seconds", "operations" ], "additionalProperties": false }, "minItems": 1, "maxItems": 100 }, "guardrails": { "type": "array", "items": { "type": "object", "properties": { "metric_id": { "type": "string" }, "comparison": { "type": "string", "enum": [ "treatment_vs_control", "absolute" ] }, "max_increase": { "type": "number" }, "minimum_exposures": { "type": "integer", "minimum": 1 }, "window_seconds": { "type": "integer", "minimum": 60 }, "action": { "type": "string", "enum": [ "pause", "rollback" ] } }, "required": [ "metric_id", "max_increase" ], "additionalProperties": false }, "minItems": 0, "maxItems": 10 } }, "additionalProperties": false }, "example": { "name": "Gradual rollout" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReleaseTemplate" }, "example": { "id": "ffrt_858vymcGFLBztDgAtMihee", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "gradual", "name": "Gradual rollout", "description": "", "steps": [ { "after_seconds": 3600, "operations": [ { "body": { "description": "Step one" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ] } ], "guardrails": [], "version": "2", "created_at": "2026-10-05T00:02:24Z", "updated_at": "2026-10-05T00:02:33Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteReleaseTemplate", "tags": [ "Release plans" ], "summary": "Delete a release template", "description": "Deletes a template without deleting release plans created from it. Credentials: a secret key.", "parameters": [ { "name": "template_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffrt_858vymcGFLBztDgAtMihee", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments": { "post": { "operationId": "createExperiment", "tags": [ "Experiments" ], "summary": "Create an experiment", "description": "Creates a draft experiment for a flag. To use it, set a flag rule or fallthrough to an `experiment` outcome. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 0, "maxItems": 20 }, "flag_key": { "$ref": "#/components/schemas/FlagKey" }, "control": { "$ref": "#/components/schemas/FlagKey" }, "weights": { "type": "array", "items": { "$ref": "#/components/schemas/Weight" }, "minItems": 2, "maxItems": 20 }, "bucket_by": { "$ref": "#/components/schemas/Selector" }, "seed": { "$ref": "#/components/schemas/ResourceKey" }, "metrics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "primary_metric_id": { "type": "string" }, "enrollment": { "type": "object", "properties": { "start_at": { "$ref": "#/components/schemas/Time" }, "end_at": { "$ref": "#/components/schemas/Time" }, "max_subjects": { "type": "integer", "minimum": 100, "maximum": 10000000 } }, "required": [ "start_at", "end_at", "max_subjects" ], "additionalProperties": false }, "attribution_seconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "analysis": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sequential", "fixed" ] }, "alpha": { "type": "number", "minimum": 0.001, "maximum": 0.2 }, "minimum_subjects": { "type": "integer", "minimum": 100 }, "minimum_duration_seconds": { "type": "integer", "minimum": 3600 }, "covariate_metric_id": { "type": [ "string", "null" ] }, "method": { "type": "string", "enum": [ "confidence_sequence", "permutation" ] }, "target_subjects_per_arm": { "type": "integer", "minimum": 100 } }, "required": [ "mode", "alpha", "minimum_subjects", "minimum_duration_seconds" ], "additionalProperties": false }, "cohort_namespace": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "flag_key", "control", "weights", "bucket_by", "seed", "metrics", "primary_metric_id", "enrollment", "attribution_seconds", "analysis" ], "additionalProperties": false }, "example": { "key": "checkout_test", "name": "Checkout test", "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400 } } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "draft", "enrolled": 0, "version": "1", "started_at": null, "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:03:06Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listExperiments", "tags": [ "Experiments" ], "summary": "List experiments", "description": "Lists experiments other than archived ones, unless `include_archived=true`. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "include_archived", "in": "query", "required": false, "description": "Whether the list has archived resources. Default false.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentList" }, "example": { "data": [ { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "draft", "enrolled": 0, "version": "1", "started_at": null, "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:03:06Z" }, { "id": "ffx_CQvMdjfHE84eRfK4L28auS", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "spare_test", "name": "Checkout test", "description": "", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "spare_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "draft", "enrolled": 0, "version": "1", "started_at": null, "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:09Z", "updated_at": "2026-10-05T00:03:09Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}": { "get": { "operationId": "getExperiment", "tags": [ "Experiments" ], "summary": "Get an experiment", "description": "Returns an experiment. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "draft", "enrolled": 0, "version": "1", "started_at": null, "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:03:06Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateExperiment", "tags": [ "Experiments" ], "summary": "Update an experiment", "description": "Updates an experiment. Once it has started, only `name`, `description`, and `tags` can change. Create a new experiment to change its design. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 0, "maxItems": 20 }, "control": { "$ref": "#/components/schemas/FlagKey" }, "weights": { "type": "array", "items": { "$ref": "#/components/schemas/Weight" }, "minItems": 2, "maxItems": 20 }, "bucket_by": { "$ref": "#/components/schemas/Selector" }, "seed": { "$ref": "#/components/schemas/ResourceKey" }, "metrics": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "primary_metric_id": { "type": "string" }, "enrollment": { "type": "object", "properties": { "start_at": { "$ref": "#/components/schemas/Time" }, "end_at": { "$ref": "#/components/schemas/Time" }, "max_subjects": { "type": "integer", "minimum": 100, "maximum": 10000000 } }, "required": [ "start_at", "end_at", "max_subjects" ], "additionalProperties": false }, "attribution_seconds": { "type": "integer", "minimum": 60, "maximum": 2592000 }, "analysis": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "sequential", "fixed" ] }, "alpha": { "type": "number", "minimum": 0.001, "maximum": 0.2 }, "minimum_subjects": { "type": "integer", "minimum": 100 }, "minimum_duration_seconds": { "type": "integer", "minimum": 3600 }, "covariate_metric_id": { "type": [ "string", "null" ] }, "method": { "type": "string", "enum": [ "confidence_sequence", "permutation" ] }, "target_subjects_per_arm": { "type": "integer", "minimum": 100 } }, "required": [ "mode", "alpha", "minimum_subjects", "minimum_duration_seconds" ], "additionalProperties": false }, "cohort_namespace": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "example": { "description": "Does the new checkout sell more?" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "Does the new checkout sell more?", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "draft", "enrolled": 0, "version": "2", "started_at": null, "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:03:18Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteExperiment", "tags": [ "Experiments" ], "summary": "Delete an experiment", "description": "Deletes an experiment that isn't running or paused and that no flag serves, with its assignments, exposures, and events. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffx_CQvMdjfHE84eRfK4L28auS", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/start": { "post": { "operationId": "startExperiment", "tags": [ "Experiments" ], "summary": "Start an experiment", "description": "Starts enrollment and publishes the frozen assignment definition as a new revision. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "Does the new checkout sell more?", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "running", "enrolled": 0, "version": "3", "started_at": "2026-10-05T00:06:39Z", "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:06:39Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/pause": { "post": { "operationId": "pauseExperiment", "tags": [ "Experiments" ], "summary": "Pause an experiment", "description": "Stops new enrollment; assigned subjects keep their variations. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "Does the new checkout sell more?", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "paused", "enrolled": 1, "version": "4", "started_at": "2026-10-05T00:06:39Z", "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:06:54Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/resume": { "post": { "operationId": "resumeExperiment", "tags": [ "Experiments" ], "summary": "Resume an experiment", "description": "Resumes enrollment, provided the enrollment window has not ended. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "Does the new checkout sell more?", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "running", "enrolled": 1, "version": "5", "started_at": "2026-10-05T00:06:39Z", "stopped_at": null, "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:06:57Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/stop": { "post": { "operationId": "stopExperiment", "tags": [ "Experiments" ], "summary": "Stop an experiment", "description": "Ends enrollment and returns flags to their fallback variations. Metric events can still be attributed to existing assignments until their attribution windows close. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "comment" ], "additionalProperties": false }, "example": { "comment": "Enough data" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "Does the new checkout sell more?", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "stopped", "enrolled": 1, "version": "6", "started_at": "2026-10-05T00:06:39Z", "stopped_at": "2026-10-05T00:07:09Z", "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:07:09Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/archive": { "post": { "operationId": "archiveExperiment", "tags": [ "Experiments" ], "summary": "Archive an experiment", "description": "Hides a stopped or completed experiment from default lists. Its results remain available. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Experiment" }, "example": { "id": "ffx_11iuayY2VkrTYqo5A98uC9", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_test", "name": "Checkout test", "description": "Does the new checkout sell more?", "tags": [], "flag_key": "checkout", "control": "off", "weights": [ { "variation": "off", "weight": 50000 }, { "variation": "on", "weight": 50000 } ], "bucket_by": "targeting_key", "seed": "checkout_test", "metrics": [ "ffm_3PihqRDi3X1ka9K5SG55oJ" ], "primary_metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "enrollment": { "start_at": "2026-10-05T00:05:03Z", "end_at": "2026-10-12T00:00:00Z", "max_subjects": 10000 }, "attribution_seconds": 86400, "analysis": { "mode": "sequential", "alpha": 0.05, "minimum_subjects": 100, "minimum_duration_seconds": 86400, "covariate_metric_id": null, "method": "bounded_hoeffding", "target_subjects_per_arm": null }, "cohort_namespace": null, "status": "archived", "enrolled": 1, "version": "7", "started_at": "2026-10-05T00:06:39Z", "stopped_at": "2026-10-05T00:07:09Z", "completed_at": null, "created_at": "2026-10-05T00:03:06Z", "updated_at": "2026-10-05T00:07:15Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/conclude": { "post": { "operationId": "concludeExperiment", "tags": [ "Experiments" ], "summary": "Conclude an experiment", "description": "Proposes a draft change set that serves the chosen variation in place of the experiment. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variation": { "$ref": "#/components/schemas/FlagKey" }, "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "variation", "comment" ], "additionalProperties": false }, "example": { "variation": "on", "comment": "Ship the new checkout" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_MghVzJxWKbtjnDF2LJNCNy", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "16", "operations": [ { "body": { "fallthrough": { "variation": "on" }, "rules": [ { "conditions": [ { "op": "in_segment", "segment": "paid" } ], "id": "paid", "serve": { "variation": "on" } } ] }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "key": "checkout", "changed_fields": [ "fallthrough" ] } ], "comment": "Conclude checkout_test with on (no results yet): Ship the new checkout", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "experiment", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:12Z", "updated_at": "2026-10-05T00:07:12Z", "expires_at": "2026-11-04T00:07:12Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/results": { "get": { "operationId": "getExperimentResults", "tags": [ "Experiments" ], "summary": "Get experiment results", "description": "Returns the latest analysis: arms, metrics, always-valid intervals, and a recommendation once data is sufficient. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResults" }, "example": { "experiment_id": "ffx_11iuayY2VkrTYqo5A98uC9", "revision": "0", "status": "insufficient_data", "method": "bounded_hoeffding_v1", "mode": "sequential", "alpha": 0.05, "data_through": "2026-10-05T00:06:51Z", "arms": [ { "variation": "off", "control": true, "enrolled": 0, "exposed": 0, "mature": 0, "allocation_mismatch": false }, { "variation": "on", "control": false, "enrolled": 1, "exposed": 1, "mature": 0, "allocation_mismatch": false } ], "comparisons": [ { "metric_id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "variation": "on", "treatment_mean": 0, "control_mean": 0, "difference": { "low": -1, "high": 1 }, "relative_lift": null, "relative_lift_reason": "control_near_zero", "verdict": "inconclusive", "diagnostic_only": null } ], "permutation": null, "diagnostics": { "unattributed_events": 0, "missing_exposure_rate": 0 }, "reasons": [ "minimum_subjects", "minimum_duration" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/assignments": { "get": { "operationId": "listAssignments", "tags": [ "Experiments" ], "summary": "List assignments", "description": "Lists assignments in enrollment order. Responses contain identity hashes, not the original identities. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentRecordList" }, "example": { "data": [ { "id": "ffas_72e85a35955a5f8efcf8503e", "identity_hash": "0805df29c7f69b794d22f28e767d0cedb162877d56eeb2e972006206c480abc2", "variation": "on", "sequence": "1", "config_revision": "13", "created_at": "2026-10-05T00:06:42Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/experiments/{experiment_id}/assignment_imports": { "post": { "operationId": "importAssignments", "tags": [ "Experiments" ], "summary": "Import assignments", "description": "Imports up to 1,000,000 newline-delimited `{\"identity\", \"variation\", \"first_exposure_at\"}` lines into a draft experiment, so that subjects keep their variations from another vendor. Motor hashes identities at once. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON objects." }, "example": "{\"identity\": \"user_1\", \"variation\": \"on\"}\n{\"identity\": \"user_2\", \"variation\": \"off\", \"first_exposure_at\": \"2026-09-01T00:00:00Z\"}\n" } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignmentImport" }, "example": { "experiment_id": "ffx_CQvMdjfHE84eRfK4L28auS", "imported": 2, "data_quality": "unknown" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/assignments": { "post": { "operationId": "assign", "tags": [ "Experiments" ], "summary": "Get an assignment", "description": "Evaluates experiment enrollment for a context. Local evaluators call this when they have no cached assignment for the experiment and subject. Each call is billed as one remote evaluation. Credentials: a secret key, a server SDK key, a client token.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "context": { "$ref": "#/components/schemas/Context" } }, "required": [ "experiment_id" ], "additionalProperties": false }, "example": { "experiment_id": "ffx_11iuayY2VkrTYqo5A98uC9", "context": { "targeting_key": "user_9" } } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Assignment" }, "example": { "eligible": true, "experiment_id": "ffx_11iuayY2VkrTYqo5A98uC9", "variation": "on", "value": true, "assignment_receipt": "motor_fa_EXAMPLE_NOT_A_REAL_SECRET" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "ClientToken": [] } ] } }, "/environments/{environment_id}/assignments/{assignment_id}": { "delete": { "operationId": "eraseAssignment", "tags": [ "Experiments" ], "summary": "Erase an assignment", "description": "Erases a subject's assignment, receipts, and events in response to a privacy request. Do not use this endpoint to change a subject's assigned variation. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "assignment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/ChangeCommentRequired" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffas_72e85a35955a5f8efcf8503e", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/identity_links": { "post": { "operationId": "linkIdentities", "tags": [ "Experiments" ], "summary": "Link identities", "description": "Links an anonymous targeting key to an identified one after your server verifies the login. The identified subject inherits the anonymous subject's assignments. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "anonymous_targeting_key": { "type": "string", "minLength": 1, "maxLength": 256 }, "identified_targeting_key": { "type": "string", "minLength": 1, "maxLength": 256 } }, "required": [ "anonymous_targeting_key", "identified_targeting_key" ], "additionalProperties": false }, "example": { "anonymous_targeting_key": "anon:4b4f8e9c-1f8e-4f5a-9d0e-2b7a6c1d3e4f", "identified_targeting_key": "user_9" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdentityLink" }, "example": { "id": "ffil_LjVCKWgGdBk2dh242Yrsy8", "anonymous_hash": "54164490bfb4a7debfc8e66eb23fa1153312db769970de6def5108bd2279dc41", "identified_hash": "0805df29c7f69b794d22f28e767d0cedb162877d56eeb2e972006206c480abc2", "created_at": "2026-10-05T00:07:00Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/identity_links/{link_id}": { "delete": { "operationId": "unlinkIdentities", "tags": [ "Experiments" ], "summary": "Erase an identity link", "description": "Erases a link and the assignments that it copied, for privacy. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "link_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/ChangeComment" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffil_LjVCKWgGdBk2dh242Yrsy8", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/layers": { "post": { "operationId": "createLayer", "tags": [ "Experiments" ], "summary": "Create a layer", "description": "Creates a layer of mutually exclusive experiments. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "name": { "$ref": "#/components/schemas/Name" }, "bucket_by": { "$ref": "#/components/schemas/Selector" }, "seed": { "$ref": "#/components/schemas/ResourceKey" }, "ranges": { "type": "array", "description": "Disjoint half-open ranges of 100,000 buckets.", "items": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "start": { "type": "integer", "minimum": 0, "maximum": 100000 }, "end": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "experiment_id", "start", "end" ], "additionalProperties": false }, "minItems": 0, "maxItems": 100 } }, "required": [ "key", "name", "bucket_by", "seed" ], "additionalProperties": false }, "example": { "key": "checkout_layer", "name": "Checkout", "bucket_by": "targeting_key", "seed": "checkout_layer", "ranges": [ { "experiment_id": "ffx_CQvMdjfHE84eRfK4L28auS", "start": 0, "end": 50000 } ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" }, "example": { "id": "ffly_7uenUpNwxcG1gwwkUv6B3B", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_layer", "name": "Checkout", "bucket_by": "targeting_key", "seed": "checkout_layer", "ranges": [ { "experiment_id": "ffx_CQvMdjfHE84eRfK4L28auS", "start": 0, "end": 50000 } ], "version": "1", "created_at": "2026-10-05T00:03:21Z", "updated_at": "2026-10-05T00:03:21Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listLayers", "tags": [ "Experiments" ], "summary": "List layers", "description": "Lists the environment's layers. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LayerList" }, "example": { "data": [ { "id": "ffly_7uenUpNwxcG1gwwkUv6B3B", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_layer", "name": "Checkout", "bucket_by": "targeting_key", "seed": "checkout_layer", "ranges": [ { "experiment_id": "ffx_CQvMdjfHE84eRfK4L28auS", "start": 0, "end": 50000 } ], "version": "1", "created_at": "2026-10-05T00:03:21Z", "updated_at": "2026-10-05T00:03:21Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/layers/{layer_id}": { "get": { "operationId": "getLayer", "tags": [ "Experiments" ], "summary": "Get a layer", "description": "Returns a layer. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "layer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" }, "example": { "id": "ffly_7uenUpNwxcG1gwwkUv6B3B", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_layer", "name": "Checkout", "bucket_by": "targeting_key", "seed": "checkout_layer", "ranges": [ { "experiment_id": "ffx_CQvMdjfHE84eRfK4L28auS", "start": 0, "end": 50000 } ], "version": "1", "created_at": "2026-10-05T00:03:21Z", "updated_at": "2026-10-05T00:03:21Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateLayer", "tags": [ "Experiments" ], "summary": "Update a layer", "description": "Updates a layer's name. Its bucket ranges can also be changed if none of its experiments are running. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "layer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "ranges": { "type": "array", "description": "Disjoint half-open ranges of 100,000 buckets.", "items": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "start": { "type": "integer", "minimum": 0, "maximum": 100000 }, "end": { "type": "integer", "minimum": 0, "maximum": 100000 } }, "required": [ "experiment_id", "start", "end" ], "additionalProperties": false }, "minItems": 0, "maxItems": 100 } }, "additionalProperties": false }, "example": { "name": "Checkout experiments" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Layer" }, "example": { "id": "ffly_7uenUpNwxcG1gwwkUv6B3B", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "checkout_layer", "name": "Checkout experiments", "bucket_by": "targeting_key", "seed": "checkout_layer", "ranges": [ { "experiment_id": "ffx_CQvMdjfHE84eRfK4L28auS", "start": 0, "end": 50000 } ], "version": "2", "created_at": "2026-10-05T00:03:21Z", "updated_at": "2026-10-05T00:03:30Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteLayer", "tags": [ "Experiments" ], "summary": "Delete a layer", "description": "Deletes a layer, provided none of its experiments are running. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "layer_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffly_7uenUpNwxcG1gwwkUv6B3B", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/metrics": { "post": { "operationId": "createMetric", "tags": [ "Experiments" ], "summary": "Create a metric", "description": "Creates a metric that experiments measure. Numeric metrics require lower and upper bounds; values outside those bounds are clamped to the nearest bound. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "kind": { "type": "string", "enum": [ "binary", "numeric", "ratio" ] }, "aggregation": { "type": "string", "enum": [ "any", "count", "sum", "mean" ] }, "lower_bound": { "type": [ "number", "null" ] }, "upper_bound": { "type": [ "number", "null" ] }, "direction": { "type": "string", "enum": [ "increase", "decrease" ] }, "numerator_metric_id": { "type": [ "string", "null" ] }, "denominator_metric_id": { "type": [ "string", "null" ] } }, "required": [ "key", "name", "kind", "aggregation", "direction" ], "additionalProperties": false }, "example": { "key": "purchase", "name": "Purchase", "kind": "binary", "aggregation": "any", "direction": "increase" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metric" }, "example": { "id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "purchase", "name": "Purchase", "description": "", "kind": "binary", "aggregation": "any", "lower_bound": 0, "upper_bound": 1, "direction": "increase", "numerator_metric_id": null, "denominator_metric_id": null, "version": "1", "created_at": "2026-10-05T00:02:54Z", "updated_at": "2026-10-05T00:02:54Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listMetrics", "tags": [ "Experiments" ], "summary": "List metrics", "description": "Lists the environment's metrics. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricList" }, "example": { "data": [ { "id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "purchase", "name": "Purchase", "description": "", "kind": "binary", "aggregation": "any", "lower_bound": 0, "upper_bound": 1, "direction": "increase", "numerator_metric_id": null, "denominator_metric_id": null, "version": "1", "created_at": "2026-10-05T00:02:54Z", "updated_at": "2026-10-05T00:02:54Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/metrics/{metric_id}": { "get": { "operationId": "getMetric", "tags": [ "Experiments" ], "summary": "Get a metric", "description": "Returns a metric. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metric_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metric" }, "example": { "id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "purchase", "name": "Purchase", "description": "", "kind": "binary", "aggregation": "any", "lower_bound": 0, "upper_bound": 1, "direction": "increase", "numerator_metric_id": null, "denominator_metric_id": null, "version": "1", "created_at": "2026-10-05T00:02:54Z", "updated_at": "2026-10-05T00:02:54Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "patch": { "operationId": "updateMetric", "tags": [ "Experiments" ], "summary": "Update a metric", "description": "Changes a metric. While a running experiment uses it, only `name` and `description` can change. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metric_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "kind": { "type": "string", "enum": [ "binary", "numeric", "ratio" ] }, "aggregation": { "type": "string", "enum": [ "any", "count", "sum", "mean" ] }, "lower_bound": { "type": [ "number", "null" ] }, "upper_bound": { "type": [ "number", "null" ] }, "direction": { "type": "string", "enum": [ "increase", "decrease" ] }, "numerator_metric_id": { "type": [ "string", "null" ] }, "denominator_metric_id": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "example": { "description": "A completed order" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Metric" }, "example": { "id": "ffm_3PihqRDi3X1ka9K5SG55oJ", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "key": "purchase", "name": "Purchase", "description": "A completed order", "kind": "binary", "aggregation": "any", "lower_bound": 0, "upper_bound": 1, "direction": "increase", "numerator_metric_id": null, "denominator_metric_id": null, "version": "2", "created_at": "2026-10-05T00:02:54Z", "updated_at": "2026-10-05T00:03:03Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "delete": { "operationId": "deleteMetric", "tags": [ "Experiments" ], "summary": "Delete a metric", "description": "Deletes a metric, provided no retained experiment or ratio metric depends on it. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "metric_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deleted" }, "example": { "id": "ffm_16TXaAvisQ5UfB1bUL542Y", "deleted": true } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/events": { "post": { "operationId": "recordEvents", "tags": [ "Experiments" ], "summary": "Record events", "description": "Records up to 1,000 exposure and metric events. Exposures aren't billed; each accepted metric event is billed at $0.03 per 1,000, from the first event. Retrying with the same idempotency key returns the original response. Events sent with a new idempotency key but previously accepted event IDs are treated as duplicates. Credentials: a secret key, a server SDK key, a publishable key, a client token.", "parameters": [ { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A UUID that you choose. Motor ignores a repeated ID for 90 days." }, "environment_id": { "type": "string" }, "occurred_at": { "$ref": "#/components/schemas/Time" }, "type": { "type": "string", "enum": [ "exposure", "metric" ] }, "assignment_receipt": { "type": "string" }, "metric_key": { "$ref": "#/components/schemas/FlagKey" }, "value": { "type": "number" }, "context": { "type": "object", "properties": { "targeting_key": { "type": "string" } }, "additionalProperties": false }, "experiment_id": { "type": "string" } }, "required": [ "id", "environment_id", "occurred_at", "type" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } }, "required": [ "events" ], "additionalProperties": false }, "example": { "events": [ { "id": "153f8171-190c-43d0-8f7c-6c38e6e83d34", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "occurred_at": "2026-10-05T00:00:00Z", "type": "exposure", "assignment_receipt": "motor_fa_EXAMPLE_NOT_A_REAL_SECRET" }, { "id": "c5c1089b-cd3c-4fca-9c88-99e5884e342a", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "occurred_at": "2026-10-05T00:00:00Z", "type": "metric", "metric_key": "purchase", "value": 1, "assignment_receipt": "motor_fa_EXAMPLE_NOT_A_REAL_SECRET" } ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventReport" }, "example": { "accepted": 2, "duplicates": 0, "unattributed": 0 } } } }, "401": { "$ref": "#/components/responses/Error401" }, "402": { "$ref": "#/components/responses/Error402" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "PublishableKey": [] }, { "ClientToken": [] } ] } }, "/environments/{environment_id}/clone": { "post": { "operationId": "cloneEnvironment", "tags": [ "Changes" ], "summary": "Clone an environment", "description": "Copies an environment's flags and segments into a new preview environment that expires. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "project_id": { "type": "string" }, "key": { "$ref": "#/components/schemas/ResourceKey" }, "name": { "$ref": "#/components/schemas/Name" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] } }, "required": [ "project_id", "key", "name" ], "additionalProperties": false }, "example": { "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "preview", "name": "Preview", "expires_at": "2026-10-06T00:00:00Z" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" }, "example": { "id": "ffe_5SiFJ2GJ2sdn64wg73uS99", "project_id": "ffp_9kunJd7bTWCR64Mv18pj45", "key": "preview", "name": "Preview", "description": "Live traffic", "revision": "1", "client_access": { "publishable_key_ids": [], "allowed_origins": [], "allow_native": false }, "approval_policy": { "required": 0, "reviewer_principal_ids": [], "allow_author": false }, "expires_at": "2026-10-06T00:00:00Z", "status": "active", "flag_count": 2, "segment_count": 1, "created_at": "2026-10-05T00:07:21Z", "updated_at": "2026-10-05T00:07:21Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/diff": { "post": { "operationId": "diffEnvironments", "tags": [ "Changes" ], "summary": "Compare environments", "description": "Compares flags of a source environment's revision with this environment. Read-only: send no idempotency key. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_environment_id": { "type": "string" }, "source_revision": { "$ref": "#/components/schemas/Revision" }, "flag_keys": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 1, "maxItems": 1000 }, "include_dependencies": { "type": "boolean" } }, "required": [ "source_environment_id", "source_revision" ], "additionalProperties": false }, "example": { "source_environment_id": "ffe_5SiFJ2GJ2sdn64wg73uS99", "source_revision": "2", "flag_keys": [ "banner" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Diff" }, "example": { "base_revision": "17", "source_revision": "2", "operations": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "body": { "name": "Banner text", "description": "Preview copy", "enabled": true, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ], "off_variation": "plain", "fallthrough": { "variation": "plain" }, "prerequisites": [], "targets": [], "rules": [], "value_schema": null, "tags": [], "owner_principal_id": null, "purpose": "release", "expires_at": null } } ], "conflicts": [] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/promotions": { "post": { "operationId": "promoteFlags", "tags": [ "Changes" ], "summary": "Promote flags", "description": "Proposes a draft change set that copies flags of a source revision into this environment. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_environment_id": { "type": "string" }, "source_revision": { "$ref": "#/components/schemas/Revision" }, "flag_keys": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 1, "maxItems": 1000 }, "include_dependencies": { "type": "boolean" }, "base_revision": { "$ref": "#/components/schemas/Revision" }, "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "source_environment_id", "source_revision", "base_revision", "comment" ], "additionalProperties": false }, "example": { "source_environment_id": "ffe_5SiFJ2GJ2sdn64wg73uS99", "source_revision": "2", "flag_keys": [ "banner" ], "base_revision": "17", "comment": "Promote the banner" } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_KZQQox6wwzEFhiWoit6Emk", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "17", "operations": [ { "body": { "description": "Preview copy", "enabled": true, "expires_at": null, "fallthrough": { "variation": "plain" }, "name": "Banner text", "off_variation": "plain", "owner_principal_id": null, "prerequisites": [], "purpose": "release", "rules": [], "tags": [], "targets": [], "value_schema": null, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ] }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Promote the banner", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "promotion", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:30Z", "updated_at": "2026-10-05T00:07:30Z", "expires_at": "2026-11-04T00:07:30Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes": { "post": { "operationId": "createChangeSet", "tags": [ "Changes" ], "summary": "Propose a change set", "description": "Creates a draft change set containing up to 1,000 operations against a base revision. Applying the change set publishes all operations together. If the base revision has changed, applying it fails with a revision conflict. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "base_revision": { "$ref": "#/components/schemas/Revision" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" }, "minItems": 1, "maxItems": 1000 }, "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "base_revision", "operations", "comment" ], "additionalProperties": false }, "example": { "base_revision": "18", "comment": "Retire the banner text", "operations": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "body": { "description": "Retiring" } } ] } } } }, "responses": { "201": { "description": "Success.", "headers": { "Location": { "description": "The URL of the new resource.", "schema": { "type": "string" } }, "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_44jMG2arwxyjzZt3kCcA7q", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "18", "operations": [ { "body": { "description": "Retiring" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Retire the banner text", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:36Z", "updated_at": "2026-10-05T00:07:36Z", "expires_at": "2026-11-04T00:07:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listChangeSets", "tags": [ "Changes" ], "summary": "List change sets", "description": "Lists change sets in a stable order, with an optional exact `status`. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Only resources with this status.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSetList" }, "example": { "data": [ { "id": "ffc_44jMG2arwxyjzZt3kCcA7q", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "18", "operations": [ { "body": { "description": "Retiring" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Retire the banner text", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:36Z", "updated_at": "2026-10-05T00:07:36Z", "expires_at": "2026-11-04T00:07:36Z" }, { "id": "ffc_KZQQox6wwzEFhiWoit6Emk", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "17", "operations": [ { "body": { "description": "Preview copy", "enabled": true, "expires_at": null, "fallthrough": { "variation": "plain" }, "name": "Banner text", "off_variation": "plain", "owner_principal_id": null, "prerequisites": [], "purpose": "release", "rules": [], "tags": [], "targets": [], "value_schema": null, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ] }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Promote the banner", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "promotion", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:30Z", "updated_at": "2026-10-05T00:07:30Z", "expires_at": "2026-11-04T00:07:30Z" }, { "id": "ffc_MghVzJxWKbtjnDF2LJNCNy", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "16", "operations": [ { "body": { "fallthrough": { "variation": "on" }, "rules": [ { "conditions": [ { "op": "in_segment", "segment": "paid" } ], "id": "paid", "serve": { "variation": "on" } } ] }, "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_VrfGhkyrB2pjGqESka3ALF", "key": "checkout", "changed_fields": [ "fallthrough" ] } ], "comment": "Conclude checkout_test with on (no results yet): Ship the new checkout", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "experiment", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:12Z", "updated_at": "2026-10-05T00:07:12Z", "expires_at": "2026-11-04T00:07:12Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes/{change_id}": { "get": { "operationId": "getChangeSet", "tags": [ "Changes" ], "summary": "Get a change set", "description": "Returns a change set with its diff and reviews. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "change_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_44jMG2arwxyjzZt3kCcA7q", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "18", "operations": [ { "body": { "description": "Retiring" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Retire the banner text", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "draft", "version": "1", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:36Z", "updated_at": "2026-10-05T00:07:36Z", "expires_at": "2026-11-04T00:07:36Z", "approval_policy": { "required": 1, "reviewer_principal_ids": [ "user_CbJvbgw5XNiJcPMi9mEavM" ], "allow_author": false } } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes/{change_id}/preview": { "post": { "operationId": "previewChangeSet", "tags": [ "Changes" ], "summary": "Preview a change set", "description": "Compares results of up to 100 contexts and flags before and after the change. Read-only: send no idempotency key. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "change_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contexts": { "type": "array", "items": { "$ref": "#/components/schemas/Context" }, "minItems": 1, "maxItems": 100 }, "flag_keys": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 1, "maxItems": 100 } }, "required": [ "contexts" ], "additionalProperties": false }, "example": { "contexts": [ { "targeting_key": "user_123" } ], "flag_keys": [ "banner" ] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangePreview" }, "example": { "base_revision": "18", "results": [ { "context_index": 0, "flag_key": "banner", "before": { "value": "Welcome", "variation": "plain", "reason": "DEFAULT", "error_code": null }, "after": { "value": "Welcome", "variation": "plain", "reason": "DEFAULT", "error_code": null }, "changed": false } ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes/{change_id}/submit": { "post": { "operationId": "submitChangeSet", "tags": [ "Changes" ], "summary": "Submit a change set", "description": "Submits a draft for review. It is approved automatically if the environment does not require approvals. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "change_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_44jMG2arwxyjzZt3kCcA7q", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "18", "operations": [ { "body": { "description": "Retiring" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Retire the banner text", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "pending", "version": "2", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:07:36Z", "updated_at": "2026-10-05T00:07:48Z", "expires_at": "2026-11-04T00:07:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes/{change_id}/review": { "post": { "operationId": "reviewChangeSet", "tags": [ "Changes" ], "summary": "Review a change set", "description": "Records a reviewer's decision. The reviewer must be a user listed in the environment's approval policy. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "change_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "decision" ], "additionalProperties": false }, "example": { "decision": "approve", "comment": "Looks right" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_44jMG2arwxyjzZt3kCcA7q", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "18", "operations": [ { "body": { "description": "Retiring" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Retire the banner text", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "approved", "version": "3", "applied_revision": null, "applied_at": null, "reviews": [ { "principal_id": "user_CbJvbgw5XNiJcPMi9mEavM", "key_id": "key_3CKBrMD1KmGksgf4ej3pmN", "decision": "approve", "comment": "Looks right", "at": "2026-10-05T00:07:51Z" } ], "created_at": "2026-10-05T00:07:36Z", "updated_at": "2026-10-05T00:07:51Z", "expires_at": "2026-11-04T00:07:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes/{change_id}/apply": { "post": { "operationId": "applyChangeSet", "tags": [ "Changes" ], "summary": "Apply a change set", "description": "Applies an approved change set as one new revision, after checking the base, approvals, and configuration again. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "change_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_44jMG2arwxyjzZt3kCcA7q", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "18", "operations": [ { "body": { "description": "Retiring" }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "description" ] } ], "comment": "Retire the banner text", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "applied", "version": "4", "applied_revision": "19", "applied_at": "2026-10-05T00:07:54Z", "reviews": [ { "principal_id": "user_CbJvbgw5XNiJcPMi9mEavM", "key_id": "key_3CKBrMD1KmGksgf4ej3pmN", "decision": "approve", "comment": "Looks right", "at": "2026-10-05T00:07:51Z" } ], "created_at": "2026-10-05T00:07:36Z", "updated_at": "2026-10-05T00:07:54Z", "expires_at": "2026-11-04T00:07:36Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/changes/{change_id}/cancel": { "post": { "operationId": "cancelChangeSet", "tags": [ "Changes" ], "summary": "Cancel a change set", "description": "Cancels an open change set. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "change_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "comment": { "$ref": "#/components/schemas/Comment" } }, "additionalProperties": false }, "example": { "comment": "Not this week" } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeSet" }, "example": { "id": "ffc_5HyScKNxfnefTuAKoJ7zfq", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "base_revision": "20", "operations": [ { "body": { "fallthrough": { "variation": "sale" } }, "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "op": "update", "resource": "flag" } ], "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "fallthrough" ] } ], "comment": "Try a sale", "author_key_id": "key_DuQaWzydzQjd8J84rbPfSd", "author_principal_id": "user_P68xcnDgjsgeCWkZpWrhXx", "source": "api", "status": "canceled", "version": "2", "applied_revision": null, "applied_at": null, "reviews": [], "created_at": "2026-10-05T00:08:00Z", "updated_at": "2026-10-05T00:08:03Z", "expires_at": "2026-11-04T00:08:00Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/export": { "get": { "operationId": "exportEnvironment", "tags": [ "Configuration as code" ], "summary": "Export an environment", "description": "Returns a Motor export of the current or a retained revision, without credentials or policies. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "revision", "in": "query", "required": false, "description": "A retained revision number. Default: the current revision.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Export" }, "example": { "format": "motor.feature_flags", "format_version": 1, "source_environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "revision": "20", "flags": [ { "key": "banner", "name": "Banner text", "description": "Retiring", "type": "string", "enabled": true, "client_visible": false, "variations": [ { "key": "plain", "value": "Welcome" }, { "key": "sale", "value": "Sale today" } ], "off_variation": "plain", "fallthrough": { "variation": "plain" }, "prerequisites": [], "targets": [], "rules": [], "value_schema": null, "tags": [], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false }, { "key": "checkout", "name": "New checkout", "description": "The checkout of 2026", "type": "boolean", "enabled": true, "client_visible": true, "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "experiment": "checkout_test", "fallback_variation": "off" }, "prerequisites": [], "targets": [], "rules": [ { "id": "paid", "conditions": [ { "segment": "paid", "op": "in_segment" } ], "serve": { "variation": "on" } } ], "value_schema": null, "tags": [ "web" ], "owner_principal_id": null, "purpose": "release", "expires_at": null, "archived": false } ], "segments": [ { "key": "paid", "name": "Paid accounts", "description": "", "groups": [ [ { "attribute": "attributes.plan", "op": "in", "values": [ "pro", "team" ] } ] ] } ], "audience_manifests": [ { "id": "ffauds_EsdpMBV91zRKnBddyK2dux", "key": "beta", "version": 1, "local_delivery": true, "members": 2, "digest": "0ff5263c14f3e95f4e6f53891bacb664a4f3f5d35b2efe68ee75a0df5143b950", "chunks": [ "99a0566fdbd9a50cd7fe12ea6281ee4657117263eb70913168441fd8cdd89e20" ] } ], "value_schemas": {} } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/sync": { "post": { "operationId": "syncEnvironment", "tags": [ "Configuration as code" ], "summary": "Sync an environment", "description": "Creates or updates flags and segments by key using Motor's export format. By default, a dry run returns a diff without saving changes. With `dry_run: false`, sync publishes immediately or proposes a change set if the environment requires approvals. Send an idempotency key only with `dry_run: false`. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "motor.feature_flags" ] }, "format_version": { "type": "integer", "minimum": 1, "maximum": 1 }, "source_environment_id": { "type": "string" }, "revision": { "$ref": "#/components/schemas/Revision" }, "flags": { "type": "array", "items": { "type": "object" } }, "segments": { "type": "array", "items": { "type": "object" } }, "audience_manifests": { "type": "array", "items": {} }, "value_schemas": { "type": "object" }, "base_revision": { "$ref": "#/components/schemas/Revision" }, "dry_run": { "type": "boolean", "description": "Default true." }, "prune_tag": { "oneOf": [ { "$ref": "#/components/schemas/FlagKey" }, { "type": "null" } ] }, "comment": { "type": "string", "maxLength": 512 } }, "required": [ "base_revision" ], "additionalProperties": false }, "example": { "base_revision": "20", "dry_run": true, "flags": [ { "key": "banner", "tags": [ "gitops" ] } ], "segments": [] } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SyncResult" }, "example": { "dry_run": true, "changed": true, "base_revision": "20", "prospective_revision": "21", "diff": [ { "op": "update", "resource": "flag", "id": "ffl_PduaHSfBcMPJXFHC8gtUyj", "key": "banner", "changed_fields": [ "tags" ] } ], "change_set": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/imports": { "post": { "operationId": "importConfiguration", "tags": [ "Configuration as code" ], "summary": "Import a configuration", "description": "Starts a job that translates a Motor or vendor export (LaunchDarkly, Unleash, GrowthBook, Flagsmith, or ConfigCat) into a draft change set. Rules that don't have the same meaning in Motor become issues that need a mapping. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "motor", "launchdarkly", "unleash", "growthbook", "flagsmith", "configcat" ] }, "document": { "$ref": "#/components/schemas/JsonValue" }, "base_revision": { "$ref": "#/components/schemas/Revision" }, "import_mode": { "type": "string", "enum": [ "merge", "replace" ] }, "prune_tag": { "oneOf": [ { "$ref": "#/components/schemas/FlagKey" }, { "type": "null" } ] }, "source_environment": { "type": [ "string", "null" ] }, "comment": { "$ref": "#/components/schemas/Comment" } }, "required": [ "format", "document", "base_revision", "comment" ], "additionalProperties": false }, "example": { "format": "motor", "base_revision": "20", "comment": "Copy production", "document": { "format": "motor.feature_flags", "format_version": 1, "flags": [ { "key": "imported", "name": "Imported", "type": "boolean", "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off", "rollout": null } } ], "segments": [] } } } } }, "responses": { "202": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } }, "Idempotency-Replayed": { "description": "`true` when this is a replay of a previously recorded response.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" }, "example": { "id": "ffi_8Vd59L8nFLjznXy3twGTgd", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "format": "motor", "source_environment": null, "import_mode": "merge", "prune_tag": null, "base_revision": "20", "comment": "Copy production", "status": "processing", "error": null, "flags": 0, "segments": 0, "issues": [], "change_set_id": null, "cohort_warning": "Motor puts subjects in rollout buckets with its own hash, so a subject can get another variation than the source gave it. Import experiment assignments to keep them.", "document_expires_at": "2026-10-12T00:08:12Z", "created_at": "2026-10-05T00:08:12Z", "updated_at": "2026-10-05T00:08:12Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] }, "get": { "operationId": "listImports", "tags": [ "Configuration as code" ], "summary": "List imports", "description": "Lists the environment's imports, newest first, for 90 days. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of results per page: 1 to 200. Defaults to 50.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value returned by the previous page.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportList" }, "example": { "data": [ { "id": "ffi_8Vd59L8nFLjznXy3twGTgd", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "format": "motor", "source_environment": null, "import_mode": "merge", "prune_tag": null, "base_revision": "20", "comment": "Copy production", "status": "needs_mapping", "error": null, "flags": 1, "segments": 0, "issues": [ { "id": "ffii_invalid_flag_imported", "path": "$", "code": "invalid_resource", "message": "`fallthrough.rollout` isn't a field here.", "resource": "flag", "proposed_key": "imported", "resolved": false } ], "change_set_id": null, "cohort_warning": "Motor puts subjects in rollout buckets with its own hash, so a subject can get another variation than the source gave it. Import experiment assignments to keep them.", "document_expires_at": "2026-10-12T00:08:12Z", "created_at": "2026-10-05T00:08:12Z", "updated_at": "2026-10-08T16:30:47Z" } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Error401" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/imports/{import_id}": { "get": { "operationId": "getImport", "tags": [ "Configuration as code" ], "summary": "Get an import", "description": "Returns an import's status (`processing`, `needs_mapping`, `ready`, or `failed`), issues, and change set. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "import_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" }, "example": { "id": "ffi_8Vd59L8nFLjznXy3twGTgd", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "format": "motor", "source_environment": null, "import_mode": "merge", "prune_tag": null, "base_revision": "20", "comment": "Copy production", "status": "needs_mapping", "error": null, "flags": 1, "segments": 0, "issues": [ { "id": "ffii_invalid_flag_imported", "path": "$", "code": "invalid_resource", "message": "`fallthrough.rollout` isn't a field here.", "resource": "flag", "proposed_key": "imported", "resolved": false } ], "change_set_id": null, "cohort_warning": "Motor puts subjects in rollout buckets with its own hash, so a subject can get another variation than the source gave it. Import experiment assignments to keep them.", "document_expires_at": "2026-10-12T00:08:12Z", "created_at": "2026-10-05T00:08:12Z", "updated_at": "2026-10-08T16:30:47Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/imports/{import_id}/mappings": { "patch": { "operationId": "mapImportIssue", "tags": [ "Configuration as code" ], "summary": "Map an import issue", "description": "Resolves import issues by replacing the affected resources with Motor flags or segments. Motor then translates and validates the import again. Credentials: a secret key.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "import_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "issue_id": { "type": "string" }, "action": { "type": "string", "enum": [ "replace" ] }, "replacement": { "type": "object", "description": "A Motor flag or segment create body." } }, "required": [ "issue_id", "action", "replacement" ], "additionalProperties": false }, "example": { "issue_id": "ffii_invalid_flag_imported", "action": "replace", "replacement": { "key": "imported", "name": "Imported", "type": "boolean", "variations": [ { "key": "off", "value": false }, { "key": "on", "value": true } ], "off_variation": "off", "fallthrough": { "variation": "off" } } } } } }, "responses": { "202": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Import" }, "example": { "id": "ffi_8Vd59L8nFLjznXy3twGTgd", "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "format": "motor", "source_environment": null, "import_mode": "merge", "prune_tag": null, "base_revision": "20", "comment": "Copy production", "status": "processing", "error": null, "flags": 1, "segments": 0, "issues": [ { "id": "ffii_invalid_flag_imported", "path": "$", "code": "invalid_resource", "message": "`fallthrough.rollout` isn't a field here.", "resource": "flag", "proposed_key": "imported", "resolved": false } ], "change_set_id": null, "cohort_warning": "Motor puts subjects in rollout buckets with its own hash, so a subject can get another variation than the source gave it. Import experiment assignments to keep them.", "document_expires_at": "2026-10-12T00:08:12Z", "created_at": "2026-10-05T00:08:12Z", "updated_at": "2026-10-05T00:08:21Z" } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] } ] } }, "/environments/{environment_id}/stream": { "get": { "operationId": "streamConfiguration", "tags": [ "Streams" ], "summary": "Stream configuration changes", "description": "A server-sent event stream: a `configuration` event with the environment's revision on connection and after each change, and `heartbeat` every 30 seconds. It ends after 15 minutes or when a credential changes; reconnect with `Last-Event-ID`. Credentials: a secret key, a server SDK key, a publishable key, a client token.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "A `text/event-stream` of invalidation events.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "event: configuration\nretry: 2000\ndata: {\"environment_id\":\"ffe_UJAs9eZep7hvba6xBh5dvY\",\"revision\":\"21\",\"config_etag\":\"\\\"ffc:ffe_UJAs9eZep7hvba6xBh5dvY:21:1\\\"\"}\n\nid: 1-44\n\n" } } }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "PublishableKey": [] }, { "ClientToken": [] } ] } }, "/environments/{environment_id}/ofrep/v1/evaluate/flags/{key}": { "post": { "operationId": "ofrepEvaluateFlag", "tags": [ "OFREP" ], "summary": "Evaluate a flag (OFREP)", "description": "OFREP 0.4.0 single-flag evaluation. Errors use the protocol's bodies. Only `200` responses are billed as remote evaluations. Credentials: a secret key, a server SDK key, a publishable key, a client token.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "properties": { "targetingKey": { "type": "string" } }, "additionalProperties": true } }, "required": [ "context" ] }, "example": { "context": { "targetingKey": "user_123", "plan": "pro" } } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfrepResult" }, "example": { "key": "banner", "value": "Welcome", "reason": "DISABLED", "variant": "plain", "metadata": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "revision": 21 } } } } }, "400": { "description": "OFREP failure, such as `INVALID_CONTEXT` or `TARGETING_KEY_MISSING`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfrepFailure" } } } }, "404": { "description": "OFREP `FLAG_NOT_FOUND`: the flag doesn't exist or the credential can't see it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfrepFailure" } } } }, "401": { "description": "The credential is missing or invalid. No body." }, "403": { "description": "The credential can't use this environment. No body." }, "429": { "description": "Rate limited, or the monthly spending limit (`X-Motor-Error: limit_reached`). `Retry-After` is an RFC 3339 time, the start of the next UTC month for the spending limit.", "headers": { "Retry-After": { "schema": { "type": "string" } }, "X-Motor-Error": { "schema": { "type": "string" } } } } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "PublishableKey": [] }, { "ClientToken": [] } ] } }, "/environments/{environment_id}/ofrep/v1/evaluate/flags": { "post": { "operationId": "ofrepEvaluateFlags", "tags": [ "OFREP" ], "summary": "Evaluate all flags (OFREP)", "description": "OFREP 0.4.0 bulk evaluation of every flag that the credential can see. A request with the response's `ETag` in `If-None-Match` gets `304` when nothing changed for this context, without a charge. Credentials: a secret key, a server SDK key, a publishable key, a client token.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "flagConfigEtag", "in": "query", "required": false, "description": "An OFREP freshness hint from an event; Motor checks results itself.", "schema": { "type": "string" } }, { "name": "flagConfigLastModified", "in": "query", "required": false, "description": "An OFREP freshness hint from an event.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "context": { "type": "object", "properties": { "targetingKey": { "type": "string" } }, "additionalProperties": true } }, "required": [ "context" ] }, "example": { "context": { "targetingKey": "user_123" } } } } }, "responses": { "200": { "description": "Success.", "headers": { "ETag": { "description": "The ETag identifying this resource or configuration revision. Use it for conditional requests.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfrepBulk" }, "example": { "flags": [ { "key": "banner", "value": "Welcome", "reason": "DISABLED", "variant": "plain", "metadata": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "revision": 21 } }, { "key": "checkout", "value": false, "reason": "STATIC", "variant": "off", "metadata": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "revision": 21 } } ], "metadata": { "environment_id": "ffe_UJAs9eZep7hvba6xBh5dvY", "revision": 21 }, "eventStreams": [ { "type": "sse", "endpoint": { "requestUri": "/feature_flags/environments/ffe_UJAs9eZep7hvba6xBh5dvY/ofrep/v1/events" }, "inactivityDelaySec": 120 } ] } } } }, "304": { "description": "Not modified for this context." }, "400": { "description": "OFREP failure of the whole request, such as `INVALID_CONTEXT`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfrepFailure" } } } }, "401": { "description": "The credential is missing or invalid. No body." }, "403": { "description": "The credential can't use this environment. No body." }, "429": { "description": "Rate limited, or the monthly spending limit (`X-Motor-Error: limit_reached`). `Retry-After` is an RFC 3339 time, the start of the next UTC month for the spending limit.", "headers": { "Retry-After": { "schema": { "type": "string" } }, "X-Motor-Error": { "schema": { "type": "string" } } } } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "PublishableKey": [] }, { "ClientToken": [] } ] } }, "/environments/{environment_id}/ofrep/v1/events": { "get": { "operationId": "ofrepEvents", "tags": [ "OFREP" ], "summary": "Stream change events (OFREP)", "description": "The OFREP event stream: `message` events with `{\"type\": \"refetchEvaluation\"}` after each change. Credentials: a secret key, a server SDK key, a publishable key, a client token.", "parameters": [ { "name": "environment_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/MotorMode" }, { "$ref": "#/components/parameters/LastEventId" } ], "responses": { "200": { "description": "A `text/event-stream` of invalidation events.", "content": { "text/event-stream": { "schema": { "type": "string" }, "example": "retry: 2000\ndata: {\"type\":\"refetchEvaluation\",\"etag\":\"\\\"ffc:ffe_UJAs9eZep7hvba6xBh5dvY:21:1\\\"\",\"lastModified\":1791158904}\n\nid: 1-44\n\n" } } }, "400": { "description": "OFREP failure, such as `INVALID_CONTEXT` or `TARGETING_KEY_MISSING`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OfrepFailure" } } } }, "401": { "description": "The credential is missing or invalid. No body." }, "403": { "description": "The credential can't use this environment. No body." }, "429": { "description": "Rate limited, or the monthly spending limit (`X-Motor-Error: limit_reached`). `Retry-After` is an RFC 3339 time, the start of the next UTC month for the spending limit.", "headers": { "Retry-After": { "schema": { "type": "string" } }, "X-Motor-Error": { "schema": { "type": "string" } } } } }, "security": [ { "SecretKey": [] }, { "SdkKey": [] }, { "PublishableKey": [] }, { "ClientToken": [] } ] } } }, "components": { "securitySchemes": { "SecretKey": { "type": "http", "scheme": "bearer", "description": "A Motor secret key, `motor_sk_...`. Keep it on your server." }, "SdkKey": { "type": "http", "scheme": "bearer", "description": "A server SDK key of one environment, `motor_ffsk_...`." }, "PublishableKey": { "type": "http", "scheme": "bearer", "description": "The publishable half of a Motor key, `motor_pk_...`, for browsers and apps. It sees only client-visible flags, with anonymous `anon:` subjects." }, "ClientToken": { "type": "http", "scheme": "bearer", "description": "A client token, `motor_ct_...`, that your server issues for one subject and chosen flags." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 to 128 printable ASCII characters that you choose for this operation. A retry with the same key and body returns the recorded response for 35 days, with `Idempotency-Replayed: true`; another body with the same key is `409`. Use a new key for a new operation.", "schema": { "type": "string", "minLength": 1, "maxLength": 128 } }, "IfMatch": { "name": "If-Match", "in": "header", "required": true, "description": "The `ETag` of the resource, or of the environment for configuration changes. A changed tag is `412`; a missing header is `428`.", "schema": { "type": "string" } }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "description": "An `ETag` from an earlier response. Motor answers `304` without a body if it still matches.", "schema": { "type": "string" } }, "ChangeComment": { "name": "X-Change-Comment", "in": "header", "required": false, "description": "An audit comment of 1 to 512 bytes. Policy changes and erasures need it.", "schema": { "type": "string", "maxLength": 512 } }, "ChangeCommentRequired": { "name": "X-Change-Comment", "in": "header", "required": true, "description": "An audit comment of 1 to 512 bytes.", "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, "MotorMode": { "name": "Motor-Mode", "in": "header", "required": false, "description": "The feature flags API does not support test mode. Omit this header or set it to `live`. Requests with `test` are rejected before processing or billing. Use a separate environment, such as staging, for tests.", "schema": { "type": "string", "enum": [ "live" ] } }, "LastEventId": { "name": "Last-Event-ID", "in": "header", "required": false, "description": "The `id` of the last event that the client got. Motor replays later events, or sends `reset` and a new snapshot.", "schema": { "type": "string" } } }, "responses": { "NotModified": { "description": "Not modified: the tag still matches." }, "Error401": { "description": "The credential is missing, invalid, expired, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error402": { "description": "The request would exceed the key's monthly spending limit (`limit_reached`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error403": { "description": "The credential can't do this here, or the account is suspended or closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error404": { "description": "The resource doesn't exist, or belongs to another team.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error409": { "description": "The request conflicts with the current state, such as `resource_in_use`, `approval_required`, or a key that exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error412": { "description": "The `If-Match` tag or the base revision is stale (`revision_conflict`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error413": { "description": "The body is too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error422": { "description": "A field isn't valid. The message names its JSON path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error428": { "description": "The request needs `If-Match`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error429": { "description": "Too many requests. `Retry-After` gives the seconds to wait.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "schema": { "type": "integer" } } } } }, "schemas": { "FlagKey": { "type": "string", "description": "A key of a flag, segment, variation, audience, experiment, or tag: a letter or digit, then letters, digits, `_`, `.` and `-`, at most 128 characters.", "pattern": "^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$" }, "ResourceKey": { "type": "string", "description": "A key of a project, environment, rule, or seed: a lowercase letter, then lowercase letters, digits, and `_`, at most 64 characters.", "pattern": "^[a-z][a-z0-9_]{0,63}$" }, "Name": { "type": "string", "description": "A name: 1 to 128 UTF-8 bytes.", "minLength": 1, "maxLength": 128 }, "Description": { "type": "string", "description": "A description: at most 2,048 UTF-8 bytes.", "maxLength": 2048 }, "Revision": { "type": "string", "description": "A configuration revision number, as a decimal string.", "pattern": "^[0-9]+$" }, "Time": { "type": "string", "description": "A UTC time in RFC 3339, such as `2026-10-05T00:00:00Z`.", "format": "date-time" }, "Comment": { "type": "string", "description": "An audit comment: 1 to 512 UTF-8 bytes.", "minLength": 1, "maxLength": 512 }, "JsonValue": { "description": "Any JSON value." }, "FlagType": { "type": "string", "enum": [ "boolean", "string", "number", "object" ], "description": "The type of a flag's values. It can't change." }, "Selector": { "description": "`targeting_key`, `attributes.`, or a path array such as `[\"attributes\", \"account\", \"plan\"]` (1 to 10 segments; array items use decimal indexes).", "oneOf": [ { "type": "string", "pattern": "^(targeting_key|attributes\\.[^.]+)$" }, { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 10 } ] }, "Problem": { "type": "object", "description": "An error. The response has no other data.", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "description": "A stable code, such as `invalid_field`, `not_found`, `revision_conflict`, `resource_in_use`, `limit_reached`, or `rate_limited`." }, "message": { "type": "string", "description": "What went wrong and what to do, in English." }, "references": { "type": "array", "description": "For `resource_in_use`: up to 20 keys of resources that refer to this one.", "items": { "type": "string" } }, "has_more": { "type": "boolean", "description": "For `resource_in_use`: whether more resources refer to this one." } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "error" ], "additionalProperties": false }, "PrimitiveCondition": { "type": "object", "description": "A comparison of one context value.", "properties": { "attribute": { "type": "string", "description": "`targeting_key` or `attributes.`. Give `attribute` or `path`, not both.", "pattern": "^(targeting_key|attributes\\.[^.]+)$" }, "path": { "type": "array", "description": "A path into nested context objects, such as `[\"attributes\", \"account\", \"plan\"]`.", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "minItems": 1, "maxItems": 10 }, "op": { "type": "string", "enum": [ "exists", "not_exists", "eq", "neq", "in", "not_in", "lt", "lte", "gt", "gte", "starts_with", "ends_with", "contains", "array_contains_any", "array_contains_all", "before", "after", "semver_eq", "semver_neq", "semver_lt", "semver_lte", "semver_gt", "semver_gte", "ip_in", "ip_not_in", "matches", "not_matches" ], "description": "The comparison operator. `exists` and `not_exists` take no `values`; `not_exists` matches missing or null attributes. Other operators return false for missing, null, or incompatible attribute types, including negative comparisons." }, "values": { "type": "array", "description": "The operands: scalars of one type. `eq`, `neq`, numeric, string, date, and version operators take exactly one.", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "minItems": 1, "maxItems": 100 }, "ignore_case": { "type": "boolean", "description": "Fold ASCII A-Z for string equality, membership, prefix, suffix, substring, and regex operators. Default false." } }, "required": [ "op" ], "additionalProperties": false }, "SegmentCondition": { "type": "object", "description": "Membership of a segment. `not_in_segment` is the negation of the segment's result, so it can match a context without attributes.", "properties": { "segment": { "$ref": "#/components/schemas/FlagKey" }, "op": { "type": "string", "enum": [ "in_segment", "not_in_segment" ] } }, "required": [ "segment", "op" ], "additionalProperties": false }, "AudienceCondition": { "type": "object", "description": "Membership of an imported audience. A missing targeting key is false for both operators.", "properties": { "audience": { "$ref": "#/components/schemas/FlagKey" }, "op": { "type": "string", "enum": [ "in_audience", "not_in_audience" ] } }, "required": [ "audience", "op" ], "additionalProperties": false }, "StrategyCondition": { "type": "object", "description": "A custom strategy that your server SDK runs, or that `strategy_results` asserts in remote evaluation.", "properties": { "strategy": { "$ref": "#/components/schemas/FlagKey" }, "version": { "type": "string", "pattern": "^[A-Za-z0-9.-]{1,64}$" }, "parameters": { "type": "object", "description": "At most 8 KiB of JSON parameters for the strategy." } }, "required": [ "strategy", "version" ], "additionalProperties": false }, "Condition": { "oneOf": [ { "$ref": "#/components/schemas/PrimitiveCondition" }, { "$ref": "#/components/schemas/SegmentCondition" }, { "$ref": "#/components/schemas/AudienceCondition" }, { "$ref": "#/components/schemas/StrategyCondition" } ] }, "Weight": { "type": "object", "properties": { "variation": { "$ref": "#/components/schemas/FlagKey" }, "weight": { "type": "integer", "description": "Weight in units of 1/100,000 (1,000 equals 1%).", "minimum": 0, "maximum": 100000 } }, "required": [ "variation", "weight" ], "additionalProperties": false }, "Rollout": { "type": "object", "description": "A percentage rollout. A subject's bucket is SHA-256 of the framed environment ID, flag key, seed, selector, and bucket value.", "properties": { "seed": { "$ref": "#/components/schemas/ResourceKey" }, "bucket_by": { "$ref": "#/components/schemas/Selector" }, "weights": { "type": "array", "description": "Ordered variation weights. The weights must total exactly 100,000.", "items": { "$ref": "#/components/schemas/Weight" }, "minItems": 1, "maxItems": 20 }, "cohort_namespace": { "type": [ "string", "null" ], "description": "Buckets subjects the same way in every flag and environment that shares the namespace." } }, "required": [ "seed", "bucket_by", "weights" ], "additionalProperties": false }, "Outcome": { "description": "The outcome to use when a rule matches or no targeting rule matches (the fallthrough).", "oneOf": [ { "type": "object", "description": "A variation.", "properties": { "variation": { "$ref": "#/components/schemas/FlagKey" } }, "required": [ "variation" ], "additionalProperties": false }, { "type": "object", "description": "A rollout.", "properties": { "rollout": { "$ref": "#/components/schemas/Rollout" } }, "required": [ "rollout" ], "additionalProperties": false }, { "type": "object", "description": "An experiment and the fallback variation for subjects who are not enrolled.", "properties": { "experiment": { "$ref": "#/components/schemas/FlagKey" }, "fallback_variation": { "$ref": "#/components/schemas/FlagKey" } }, "required": [ "experiment", "fallback_variation" ], "additionalProperties": false } ] }, "Variation": { "type": "object", "description": "A variation has a stable key and a value matching the flag's type.", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "value": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "key", "value" ], "additionalProperties": false }, "Target": { "type": "object", "properties": { "variation": { "$ref": "#/components/schemas/FlagKey" }, "include": { "type": "array", "description": "Targeting keys that get the variation.", "items": { "type": "string", "minLength": 1, "maxLength": 256 } }, "exclude": { "type": "array", "description": "Targeting keys that this target never matches.", "items": { "type": "string", "minLength": 1, "maxLength": 256 } } }, "required": [ "variation", "include" ], "additionalProperties": false }, "Rule": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/ResourceKey" }, "conditions": { "type": "array", "description": "All conditions must match.", "items": { "$ref": "#/components/schemas/Condition" }, "minItems": 1, "maxItems": 20 }, "serve": { "$ref": "#/components/schemas/Outcome" } }, "required": [ "id", "conditions", "serve" ], "additionalProperties": false }, "Prerequisite": { "type": "object", "description": "The prerequisite flag must be enabled and return this variation.", "properties": { "flag_key": { "$ref": "#/components/schemas/FlagKey" }, "variation": { "$ref": "#/components/schemas/FlagKey" } }, "required": [ "flag_key", "variation" ], "additionalProperties": false }, "ValueSchema": { "type": "object", "description": "Motor's schema subset for object and string values: `type`, `properties`, `required`, `additional_properties`, `items`, `enum`, `minimum`, `maximum`, `min_length`, `max_length`. Every variation must match it." }, "FlagCreate": { "type": "object", "description": "A new flag.", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "type": { "$ref": "#/components/schemas/FlagType" }, "enabled": { "type": "boolean", "description": "Default false. A disabled flag serves `off_variation` with reason `DISABLED`." }, "client_visible": { "type": "boolean", "description": "Whether publishable keys and client tokens can evaluate the flag. Default false." }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/Variation" }, "minItems": 1, "maxItems": 20 }, "off_variation": { "$ref": "#/components/schemas/FlagKey" }, "fallthrough": { "$ref": "#/components/schemas/Outcome" }, "prerequisites": { "type": "array", "items": { "$ref": "#/components/schemas/Prerequisite" }, "minItems": 0, "maxItems": 10 }, "targets": { "type": "array", "description": "At most 10,000 targeting keys in all.", "items": { "$ref": "#/components/schemas/Target" }, "minItems": 0, "maxItems": 20 }, "rules": { "type": "array", "description": "Rules are evaluated in order. The first matching rule determines the result.", "items": { "$ref": "#/components/schemas/Rule" }, "minItems": 0, "maxItems": 50 }, "value_schema": { "oneOf": [ { "$ref": "#/components/schemas/ValueSchema" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 0, "maxItems": 20, "uniqueItems": true }, "owner_principal_id": { "type": [ "string", "null" ] }, "purpose": { "type": "string", "enum": [ "release", "experiment", "permission", "operational", "migration" ], "description": "Default `release`." }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "archived": { "type": "boolean", "description": "Archived flags are disabled and excluded from configuration snapshots." } }, "required": [ "key", "name", "type", "variations", "off_variation", "fallthrough" ], "additionalProperties": false }, "FlagUpdate": { "type": "object", "description": "The fields to change. Omitted fields keep their current values; supplied arrays replace the existing arrays in full.", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "enabled": { "type": "boolean", "description": "Default false. A disabled flag serves `off_variation` with reason `DISABLED`." }, "client_visible": { "type": "boolean", "description": "Whether publishable keys and client tokens can evaluate the flag. Default false." }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/Variation" }, "minItems": 1, "maxItems": 20 }, "off_variation": { "$ref": "#/components/schemas/FlagKey" }, "fallthrough": { "$ref": "#/components/schemas/Outcome" }, "prerequisites": { "type": "array", "items": { "$ref": "#/components/schemas/Prerequisite" }, "minItems": 0, "maxItems": 10 }, "targets": { "type": "array", "description": "At most 10,000 targeting keys in all.", "items": { "$ref": "#/components/schemas/Target" }, "minItems": 0, "maxItems": 20 }, "rules": { "type": "array", "description": "Rules are evaluated in order. The first matching rule determines the result.", "items": { "$ref": "#/components/schemas/Rule" }, "minItems": 0, "maxItems": 50 }, "value_schema": { "oneOf": [ { "$ref": "#/components/schemas/ValueSchema" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/FlagKey" }, "minItems": 0, "maxItems": 20, "uniqueItems": true }, "owner_principal_id": { "type": [ "string", "null" ] }, "purpose": { "type": "string", "enum": [ "release", "experiment", "permission", "operational", "migration" ], "description": "Default `release`." }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "archived": { "type": "boolean", "description": "Archived flags are disabled and excluded from configuration snapshots." } }, "additionalProperties": false }, "SegmentCreate": { "type": "object", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "groups": { "type": "array", "description": "A context matches the segment if it matches every condition in any one group. Segments cannot refer to other segments.", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" }, "minItems": 1, "maxItems": 20 }, "minItems": 1, "maxItems": 20 } }, "required": [ "key", "name", "groups" ], "additionalProperties": false }, "SegmentUpdate": { "type": "object", "properties": { "name": { "$ref": "#/components/schemas/Name" }, "description": { "$ref": "#/components/schemas/Description" }, "groups": { "type": "array", "description": "A context matches the segment if it matches every condition in any one group. Segments cannot refer to other segments.", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" }, "minItems": 1, "maxItems": 20 }, "minItems": 1, "maxItems": 20 } }, "additionalProperties": false }, "ClientAccess": { "type": "object", "properties": { "publishable_key_ids": { "type": "array", "description": "Publishable halves of these Motor keys can evaluate client-visible flags.", "items": { "type": "string" } }, "allowed_origins": { "type": "array", "description": "Exact browser origins, such as `https://app.example.com`.", "items": { "type": "string" } }, "allow_native": { "type": "boolean", "description": "Whether requests without an `Origin` header, from mobile and desktop apps, can evaluate." } }, "additionalProperties": false }, "ApprovalPolicy": { "type": "object", "properties": { "required": { "type": "integer", "description": "Number of approvals required for each change: 0 to 5.", "minimum": 0, "maximum": 5 }, "reviewer_principal_ids": { "type": "array", "items": { "type": "string" } }, "allow_author": { "type": "boolean", "description": "Must be false when `required` is positive." } }, "additionalProperties": false }, "Context": { "type": "object", "description": "An evaluation context.", "properties": { "targeting_key": { "type": "string", "description": "The subject: 1 to 256 UTF-8 bytes. A publishable key sends `anon:`.", "minLength": 1, "maxLength": 256 }, "attributes": { "type": "object", "description": "At most 50 attributes; nested to depth 10, at most 1,000 values and 16 KiB in all." } }, "additionalProperties": false }, "Operation": { "type": "object", "description": "One operation in a change set.", "properties": { "op": { "type": "string", "enum": [ "create", "update", "delete" ] }, "resource": { "type": "string", "enum": [ "flag", "segment", "environment" ] }, "id": { "type": "string", "description": "The resource's ID, for `update` and `delete`." }, "body": { "type": "object", "description": "The resource fields to create or update." } }, "required": [ "op", "resource" ], "additionalProperties": false }, "Wanted": { "type": "object", "description": "A flag to evaluate, its expected type, and the value to use if it can't be evaluated.", "properties": { "key": { "$ref": "#/components/schemas/FlagKey" }, "type": { "$ref": "#/components/schemas/FlagType" }, "default": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "key", "type", "default" ], "additionalProperties": false }, "Project": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "environment_count": { "type": "integer" }, "version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "key", "name", "description", "environment_count", "version", "created_at", "updated_at" ], "additionalProperties": false }, "ProjectList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Deleted": { "type": "object", "description": "A deleted resource.", "properties": { "id": { "type": "string" }, "deleted": { "const": true } }, "required": [ "id", "deleted" ], "additionalProperties": false }, "Environment": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "revision": { "type": "string" }, "client_access": { "$ref": "#/components/schemas/ClientAccess" }, "approval_policy": { "$ref": "#/components/schemas/ApprovalPolicy" }, "expires_at": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "flag_count": { "type": "integer" }, "segment_count": { "type": "integer" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "key", "name", "description", "revision", "client_access", "approval_policy", "expires_at", "status", "flag_count", "segment_count", "created_at", "updated_at" ], "additionalProperties": false }, "EnvironmentList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Flag": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "enabled": { "type": "boolean" }, "client_visible": { "type": "boolean" }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/Variation" } }, "off_variation": { "type": "string" }, "fallthrough": { "$ref": "#/components/schemas/Outcome" }, "prerequisites": { "type": "array", "items": { "$ref": "#/components/schemas/Prerequisite" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" } }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } }, "value_schema": { "$ref": "#/components/schemas/JsonValue" }, "tags": { "type": "array", "items": { "type": "string" } }, "owner_principal_id": { "$ref": "#/components/schemas/JsonValue" }, "purpose": { "type": "string" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "archived": { "type": "boolean" }, "revision": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "key", "name", "description", "type", "enabled", "client_visible", "variations", "off_variation", "fallthrough", "prerequisites", "targets", "rules", "value_schema", "tags", "owner_principal_id", "purpose", "expires_at", "archived", "revision", "created_at", "updated_at" ], "additionalProperties": false }, "FlagList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Flag" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "FlagStatistics": { "type": "object", "properties": { "flag_key": { "type": "string" }, "coverage": { "type": "string" }, "usage_status": { "type": "string" }, "last_evaluated_at": { "type": "string" }, "total": { "type": "integer" }, "error_rate": { "type": "integer" }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "hour": { "type": "string" }, "counts": { "type": "array", "items": { "type": "object", "properties": { "variation": { "type": "string" }, "reason": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "variation", "reason", "count" ], "additionalProperties": false } } }, "required": [ "hour", "counts" ], "additionalProperties": false } } }, "required": [ "flag_key", "coverage", "usage_status", "last_evaluated_at", "total", "error_rate", "buckets" ], "additionalProperties": false }, "CodeReferenceList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CodeReference" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Segment": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "groups": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } } }, "revision": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "key", "name", "description", "groups", "revision", "created_at", "updated_at" ], "additionalProperties": false }, "SegmentList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Segment" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Configuration": { "type": "object", "properties": { "audiences": { "type": "array", "items": {} }, "environment_id": { "type": "string" }, "experiments": { "type": "array", "items": {} }, "flags": { "type": "array", "items": { "type": "object", "properties": { "client_visible": { "type": "boolean" }, "enabled": { "type": "boolean" }, "fallthrough": { "$ref": "#/components/schemas/Outcome" }, "key": { "type": "string" }, "off_variation": { "type": "string" }, "prerequisites": { "type": "array", "items": { "$ref": "#/components/schemas/Prerequisite" } }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" } }, "type": { "type": "string" }, "value_schema": { "$ref": "#/components/schemas/JsonValue" }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/Variation" } } }, "required": [ "client_visible", "enabled", "fallthrough", "key", "off_variation", "prerequisites", "rules", "targets", "type", "value_schema", "variations" ], "additionalProperties": false } }, "hash_algorithm": { "type": "string" }, "revision": { "type": "string" }, "schema_version": { "type": "integer" }, "segments": { "type": "array", "items": { "type": "object", "properties": { "groups": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } } }, "key": { "type": "string" } }, "required": [ "groups", "key" ], "additionalProperties": false } }, "strategies": { "type": "array", "items": {} } }, "required": [ "audiences", "environment_id", "experiments", "flags", "hash_algorithm", "revision", "schema_version", "segments", "strategies" ], "additionalProperties": false }, "RevisionMetadataList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RevisionMetadata" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "RevisionSnapshot": { "type": "object", "properties": { "revision": { "type": "string" }, "created_at": { "type": "string" }, "actor_key_id": { "type": "string" }, "action": { "type": "string" }, "comment": { "$ref": "#/components/schemas/JsonValue" }, "restored_from": { "$ref": "#/components/schemas/JsonValue" }, "snapshot": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "revision", "created_at", "actor_key_id", "action", "comment", "restored_from", "snapshot" ], "additionalProperties": false }, "AuditEventList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "SdkKeySecret": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "name": { "type": "string" }, "owner_key_id": { "type": "string" }, "created_at": { "type": "string" }, "revoked_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "secret": { "type": "string" } }, "required": [ "id", "environment_id", "name", "owner_key_id", "created_at", "revoked_at", "secret" ], "additionalProperties": false }, "SdkKeyList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SdkKey" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Limits": { "type": "object", "properties": { "configuration_version": { "type": "string" }, "data": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "configuration_version", "data" ], "additionalProperties": false }, "AccessPolicy": { "type": "object", "properties": { "version": { "type": "string" }, "grants": { "type": "array", "items": { "type": "object", "properties": { "principal_id": { "type": "string" }, "project_ids": { "type": "array", "items": {} }, "environment_ids": { "type": "array", "items": {} }, "roles": { "type": "array", "items": { "type": "string" } } }, "required": [ "principal_id", "project_ids", "environment_ids", "roles" ], "additionalProperties": false } }, "default_role": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "version", "grants", "default_role", "updated_at" ], "additionalProperties": false }, "EvaluationResults": { "type": "object", "properties": { "environment_id": { "type": "string" }, "revision": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "variation": { "type": "string" }, "reason": { "type": "string" }, "rule_id": { "type": [ "string", "null" ] }, "prerequisite_key": { "$ref": "#/components/schemas/JsonValue" }, "error_code": { "$ref": "#/components/schemas/JsonValue" }, "experiment": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "key", "value", "variation", "reason", "rule_id", "prerequisite_key", "error_code", "experiment" ], "additionalProperties": false } } }, "required": [ "environment_id", "revision", "results" ], "additionalProperties": false }, "CountReport": { "type": "object", "properties": { "batch_id": { "type": "string" }, "accepted": { "type": "boolean" }, "duplicate": { "type": "boolean" } }, "required": [ "batch_id", "accepted", "duplicate" ], "additionalProperties": false }, "DependencyGraph": { "type": "object", "properties": { "revision": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" } }, "required": [ "type", "id", "key" ], "additionalProperties": false } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "kind": { "type": "string" } }, "required": [ "from", "to", "kind" ], "additionalProperties": false } } }, "required": [ "revision", "nodes", "edges" ], "additionalProperties": false }, "Preview": { "type": "object", "properties": { "environment_id": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "variation": { "type": "string" }, "reason": { "type": "string" }, "rule_id": { "type": "string" }, "prerequisite_key": { "$ref": "#/components/schemas/JsonValue" }, "error_code": { "$ref": "#/components/schemas/JsonValue" }, "experiment": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "key", "value", "variation", "reason", "rule_id", "prerequisite_key", "error_code", "experiment" ], "additionalProperties": false } }, "trace": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "environment_id", "results", "trace" ], "additionalProperties": false }, "CodeReferenceReport": { "type": "object", "properties": { "repository": { "type": "string" }, "branch": { "type": "string" }, "commit": { "type": "string" }, "scanned_at": { "type": "string" }, "reference_count": { "type": "integer" } }, "required": [ "repository", "branch", "commit", "scanned_at", "reference_count" ], "additionalProperties": false }, "Audience": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "match_by": { "type": "string" }, "local_delivery": { "type": "boolean" }, "committed_version": { "$ref": "#/components/schemas/JsonValue" }, "version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "audience_id": { "type": "string" }, "status": { "type": "string" }, "members": { "type": "integer" }, "duplicates": { "type": "integer" }, "digest": { "type": "string" }, "chunk_count": { "type": "integer" }, "errors": { "type": "array", "items": {} }, "finished_at": { "type": "string" } }, "required": [ "id", "version", "created_at" ], "additionalProperties": false }, "AudienceList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "AudienceImport": { "type": "object", "properties": { "id": { "type": "string" }, "audience_id": { "type": "string" }, "status": { "type": "string" }, "members": { "type": "integer" }, "duplicates": { "type": "integer" }, "digest": { "type": [ "string", "null" ] }, "chunk_count": { "type": "integer" }, "errors": { "type": "array", "items": {} }, "version": { "$ref": "#/components/schemas/JsonValue" }, "created_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "id", "audience_id", "status", "members", "duplicates", "digest", "chunk_count", "errors", "version", "created_at", "finished_at" ], "additionalProperties": false }, "AudienceChunk": { "type": "object", "properties": { "audience_id": { "type": "string" }, "format": { "type": "string" }, "hashes": { "type": "array", "items": { "type": "string" } }, "index": { "type": "integer" } }, "required": [ "audience_id", "format", "hashes", "index" ], "additionalProperties": false }, "ReleasePlan": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "name": { "type": "string" }, "base_revision": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "at": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } }, "required": [ "at", "operations" ], "additionalProperties": false } }, "guardrails": { "type": "array", "items": {} }, "comment": { "type": "string" }, "status": { "type": "string" }, "change_id": { "$ref": "#/components/schemas/JsonValue" }, "next_step": { "type": "integer" }, "applied_steps": { "type": "array", "items": {} }, "history": { "type": "array", "items": {} }, "version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "name", "base_revision", "steps", "guardrails", "comment", "status", "change_id", "next_step", "applied_steps", "history", "version", "created_at", "updated_at" ], "additionalProperties": false }, "ReleasePlanList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReleasePlan" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "ReleaseTemplate": { "type": "object", "properties": { "id": { "type": "string" }, "project_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "after_seconds": { "type": "integer" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } } }, "required": [ "after_seconds", "operations" ], "additionalProperties": false } }, "guardrails": { "type": "array", "items": {} }, "version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "project_id", "key", "name", "description", "steps", "guardrails", "version", "created_at", "updated_at" ], "additionalProperties": false }, "ReleaseTemplateList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReleaseTemplate" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Experiment": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": {} }, "flag_key": { "type": "string" }, "control": { "type": "string" }, "weights": { "type": "array", "items": { "$ref": "#/components/schemas/Weight" } }, "bucket_by": { "$ref": "#/components/schemas/Selector" }, "seed": { "type": "string" }, "metrics": { "type": "array", "items": { "type": "string" } }, "primary_metric_id": { "type": "string" }, "enrollment": { "type": "object", "properties": { "start_at": { "type": "string" }, "end_at": { "type": "string" }, "max_subjects": { "type": "integer" } }, "required": [ "start_at", "end_at", "max_subjects" ], "additionalProperties": false }, "attribution_seconds": { "type": "integer" }, "analysis": { "type": "object", "properties": { "mode": { "type": "string" }, "alpha": { "type": "number" }, "minimum_subjects": { "type": "integer" }, "minimum_duration_seconds": { "type": "integer" }, "covariate_metric_id": { "$ref": "#/components/schemas/JsonValue" }, "method": { "type": "string" }, "target_subjects_per_arm": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "mode", "alpha", "minimum_subjects", "minimum_duration_seconds", "covariate_metric_id", "method", "target_subjects_per_arm" ], "additionalProperties": false }, "cohort_namespace": { "$ref": "#/components/schemas/JsonValue" }, "status": { "type": "string" }, "enrolled": { "type": "integer" }, "version": { "type": "string" }, "started_at": { "type": [ "string", "null" ] }, "stopped_at": { "type": [ "string", "null" ] }, "completed_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "key", "name", "description", "tags", "flag_key", "control", "weights", "bucket_by", "seed", "metrics", "primary_metric_id", "enrollment", "attribution_seconds", "analysis", "cohort_namespace", "status", "enrolled", "version", "started_at", "stopped_at", "completed_at", "created_at", "updated_at" ], "additionalProperties": false }, "ExperimentList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Experiment" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "ChangeSet": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "base_revision": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } }, "diff": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "resource": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "changed_fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "op", "resource", "id", "key", "changed_fields" ], "additionalProperties": false } }, "comment": { "type": "string" }, "author_key_id": { "type": "string" }, "author_principal_id": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string" }, "applied_revision": { "type": [ "string", "null" ] }, "applied_at": { "type": [ "string", "null" ] }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "principal_id": { "type": "string" }, "key_id": { "type": "string" }, "decision": { "type": "string" }, "comment": { "type": "string" }, "at": { "type": "string" } }, "required": [ "principal_id", "key_id", "decision", "comment", "at" ], "additionalProperties": false } }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "expires_at": { "type": "string" }, "approval_policy": { "$ref": "#/components/schemas/ApprovalPolicy" } }, "required": [ "id", "environment_id", "base_revision", "operations", "diff", "comment", "author_key_id", "author_principal_id", "source", "status", "version", "applied_revision", "applied_at", "reviews", "created_at", "updated_at", "expires_at" ], "additionalProperties": false }, "ExperimentResults": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "revision": { "type": "string" }, "status": { "type": "string" }, "method": { "type": "string" }, "mode": { "type": "string" }, "alpha": { "type": "number" }, "data_through": { "type": "string" }, "arms": { "type": "array", "items": { "type": "object", "properties": { "variation": { "type": "string" }, "control": { "type": "boolean" }, "enrolled": { "type": "integer" }, "exposed": { "type": "integer" }, "mature": { "type": "integer" }, "allocation_mismatch": { "type": "boolean" } }, "required": [ "variation", "control", "enrolled", "exposed", "mature", "allocation_mismatch" ], "additionalProperties": false } }, "comparisons": { "type": "array", "items": { "type": "object", "properties": { "metric_id": { "type": "string" }, "variation": { "type": "string" }, "treatment_mean": { "type": "integer" }, "control_mean": { "type": "integer" }, "difference": { "type": "object", "properties": { "low": { "type": "integer" }, "high": { "type": "integer" } }, "required": [ "low", "high" ], "additionalProperties": false }, "relative_lift": { "$ref": "#/components/schemas/JsonValue" }, "relative_lift_reason": { "type": "string" }, "verdict": { "type": "string" }, "diagnostic_only": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "metric_id", "variation", "treatment_mean", "control_mean", "difference", "relative_lift", "relative_lift_reason", "verdict", "diagnostic_only" ], "additionalProperties": false } }, "permutation": { "$ref": "#/components/schemas/JsonValue" }, "diagnostics": { "type": "object", "properties": { "unattributed_events": { "type": "integer" }, "missing_exposure_rate": { "type": "integer" } }, "required": [ "unattributed_events", "missing_exposure_rate" ], "additionalProperties": false }, "reasons": { "type": "array", "items": { "type": "string" } } }, "required": [ "experiment_id", "revision", "status", "method", "mode", "alpha", "data_through", "arms", "comparisons", "permutation", "diagnostics", "reasons" ], "additionalProperties": false }, "AssignmentRecordList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AssignmentRecord" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "AssignmentImport": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "imported": { "type": "integer" }, "data_quality": { "type": "string" } }, "required": [ "experiment_id", "imported", "data_quality" ], "additionalProperties": false }, "Assignment": { "type": "object", "properties": { "eligible": { "type": "boolean" }, "experiment_id": { "type": "string" }, "variation": { "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "assignment_receipt": { "type": "string" } }, "required": [ "eligible", "experiment_id", "variation", "value", "assignment_receipt" ], "additionalProperties": false }, "IdentityLink": { "type": "object", "properties": { "id": { "type": "string" }, "anonymous_hash": { "type": "string" }, "identified_hash": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "anonymous_hash", "identified_hash", "created_at" ], "additionalProperties": false }, "Layer": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "bucket_by": { "$ref": "#/components/schemas/Selector" }, "seed": { "type": "string" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "experiment_id": { "type": "string" }, "start": { "type": "integer" }, "end": { "type": "integer" } }, "required": [ "experiment_id", "start", "end" ], "additionalProperties": false } }, "version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "key", "name", "bucket_by", "seed", "ranges", "version", "created_at", "updated_at" ], "additionalProperties": false }, "LayerList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Layer" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "Metric": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "aggregation": { "type": "string" }, "lower_bound": { "type": "integer" }, "upper_bound": { "type": "integer" }, "direction": { "type": "string" }, "numerator_metric_id": { "$ref": "#/components/schemas/JsonValue" }, "denominator_metric_id": { "$ref": "#/components/schemas/JsonValue" }, "version": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "key", "name", "description", "kind", "aggregation", "lower_bound", "upper_bound", "direction", "numerator_metric_id", "denominator_metric_id", "version", "created_at", "updated_at" ], "additionalProperties": false }, "MetricList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "EventReport": { "type": "object", "properties": { "accepted": { "type": "integer" }, "duplicates": { "type": "integer" }, "unattributed": { "type": "integer" } }, "required": [ "accepted", "duplicates", "unattributed" ], "additionalProperties": false }, "Diff": { "type": "object", "properties": { "base_revision": { "type": "string" }, "source_revision": { "type": "string" }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/Operation" } }, "conflicts": { "type": "array", "items": {} } }, "required": [ "base_revision", "source_revision", "operations", "conflicts" ], "additionalProperties": false }, "ChangeSetList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChangeSet" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "ChangePreview": { "type": "object", "properties": { "base_revision": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "context_index": { "type": "integer" }, "flag_key": { "type": "string" }, "before": { "$ref": "#/components/schemas/JsonValue" }, "after": { "$ref": "#/components/schemas/JsonValue" }, "changed": { "type": "boolean" } }, "required": [ "context_index", "flag_key", "before", "after", "changed" ], "additionalProperties": false } } }, "required": [ "base_revision", "results" ], "additionalProperties": false }, "Export": { "type": "object", "properties": { "format": { "type": "string" }, "format_version": { "type": "integer" }, "source_environment_id": { "type": "string" }, "revision": { "type": "string" }, "flags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "enabled": { "type": "boolean" }, "client_visible": { "type": "boolean" }, "variations": { "type": "array", "items": { "$ref": "#/components/schemas/Variation" } }, "off_variation": { "type": "string" }, "fallthrough": { "$ref": "#/components/schemas/Outcome" }, "prerequisites": { "type": "array", "items": { "$ref": "#/components/schemas/Prerequisite" } }, "targets": { "type": "array", "items": { "$ref": "#/components/schemas/Target" } }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/Rule" } }, "value_schema": { "$ref": "#/components/schemas/JsonValue" }, "tags": { "type": "array", "items": { "type": "string" } }, "owner_principal_id": { "$ref": "#/components/schemas/JsonValue" }, "purpose": { "type": "string" }, "expires_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] }, "archived": { "type": "boolean" } }, "required": [ "key", "name", "description", "type", "enabled", "client_visible", "variations", "off_variation", "fallthrough", "prerequisites", "targets", "rules", "value_schema", "tags", "owner_principal_id", "purpose", "expires_at", "archived" ], "additionalProperties": false } }, "segments": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "groups": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" } } } }, "required": [ "key", "name", "description", "groups" ], "additionalProperties": false } }, "audience_manifests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "version": { "type": "integer" }, "local_delivery": { "type": "boolean" }, "members": { "type": "integer" }, "digest": { "type": "string" }, "chunks": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "key", "version", "local_delivery", "members", "digest", "chunks" ], "additionalProperties": false } }, "value_schemas": { "type": "object", "properties": {}, "additionalProperties": false } }, "required": [ "format", "format_version", "source_environment_id", "revision", "flags", "segments", "audience_manifests", "value_schemas" ], "additionalProperties": false }, "SyncResult": { "type": "object", "properties": { "dry_run": { "type": "boolean" }, "changed": { "type": "boolean" }, "base_revision": { "type": "string" }, "prospective_revision": { "type": "string" }, "diff": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" }, "resource": { "type": "string" }, "id": { "type": "string" }, "key": { "type": "string" }, "changed_fields": { "type": "array", "items": { "type": "string" } } }, "required": [ "op", "resource", "id", "key", "changed_fields" ], "additionalProperties": false } }, "change_set": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "dry_run", "changed", "base_revision", "prospective_revision", "diff", "change_set" ], "additionalProperties": false }, "Import": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "format": { "type": "string" }, "source_environment": { "$ref": "#/components/schemas/JsonValue" }, "import_mode": { "type": "string" }, "prune_tag": { "$ref": "#/components/schemas/JsonValue" }, "base_revision": { "type": "string" }, "comment": { "type": "string" }, "status": { "type": "string" }, "error": { "$ref": "#/components/schemas/JsonValue" }, "flags": { "type": "integer" }, "segments": { "type": "integer" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "path": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "resource": { "type": "string" }, "proposed_key": { "type": "string" }, "resolved": { "type": "boolean" } }, "required": [ "id", "path", "code", "message", "resource", "proposed_key", "resolved" ], "additionalProperties": false } }, "change_set_id": { "$ref": "#/components/schemas/JsonValue" }, "cohort_warning": { "type": "string" }, "document_expires_at": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "environment_id", "format", "source_environment", "import_mode", "prune_tag", "base_revision", "comment", "status", "error", "flags", "segments", "issues", "change_set_id", "cohort_warning", "document_expires_at", "created_at", "updated_at" ], "additionalProperties": false }, "ImportList": { "type": "object", "description": "A single page of results.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Import" } }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass this value as `cursor` to fetch the next page. A null value means there are no more results." } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "CodeReference": { "type": "object", "properties": { "repository": { "type": "string" }, "branch": { "type": "string" }, "commit": { "type": "string" }, "path": { "type": "string" }, "line": { "type": "integer" }, "url": { "type": "string" }, "scanned_at": { "type": "string" } }, "required": [ "repository", "branch", "commit", "path", "line", "url", "scanned_at" ], "additionalProperties": false }, "RevisionMetadata": { "type": "object", "properties": { "revision": { "type": "string" }, "created_at": { "type": "string" }, "actor_key_id": { "type": "string" }, "action": { "type": "string" }, "comment": { "$ref": "#/components/schemas/JsonValue" }, "restored_from": { "$ref": "#/components/schemas/JsonValue" } }, "required": [ "revision", "created_at", "actor_key_id", "action", "comment", "restored_from" ], "additionalProperties": false }, "AuditEvent": { "type": "object", "properties": { "id": { "type": "string" }, "sequence": { "type": "string" }, "at": { "type": "string" }, "environment_id": { "type": "string" }, "environment_key": { "type": "string" }, "resource_type": { "type": "string" }, "resource_id": { "type": "string" }, "resource_key": { "type": "string" }, "action": { "type": "string" }, "actor_key_id": { "type": "string" }, "actor_name": { "type": "string" }, "principal_id": { "type": "string" }, "revision_before": { "type": [ "string", "null" ] }, "revision_after": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "changed_fields": { "type": "array", "items": { "type": "string" } }, "before_digest": { "type": [ "string", "null" ] }, "after_digest": { "type": "string" } }, "required": [ "id", "sequence", "at", "environment_id", "environment_key", "resource_type", "resource_id", "resource_key", "action", "actor_key_id", "actor_name", "principal_id", "revision_before", "revision_after", "comment", "changed_fields", "before_digest", "after_digest" ], "additionalProperties": false }, "SdkKey": { "type": "object", "properties": { "id": { "type": "string" }, "environment_id": { "type": "string" }, "name": { "type": "string" }, "owner_key_id": { "type": "string" }, "created_at": { "type": "string" }, "revoked_at": { "oneOf": [ { "$ref": "#/components/schemas/Time" }, { "type": "null" } ] } }, "required": [ "id", "environment_id", "name", "owner_key_id", "created_at", "revoked_at" ], "additionalProperties": false }, "AssignmentRecord": { "type": "object", "properties": { "id": { "type": "string" }, "identity_hash": { "type": "string" }, "variation": { "type": "string" }, "sequence": { "type": "string" }, "config_revision": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "identity_hash", "variation", "sequence", "config_revision", "created_at" ], "additionalProperties": false }, "OfrepResult": { "type": "object", "description": "OFREP `evaluationSuccess`: `key`, `value`, `reason` (`STATIC`, `TARGETING_MATCH`, `SPLIT`, or `DISABLED`), `variant`, and scalar `metadata` with `environment_id`, `revision`, and for an experiment `experiment_id` and `assignment_receipt`.", "required": [ "key", "reason" ], "properties": { "key": { "type": "string" }, "value": { "$ref": "#/components/schemas/JsonValue" }, "reason": { "type": "string", "enum": [ "STATIC", "TARGETING_MATCH", "SPLIT", "DISABLED", "UNKNOWN" ] }, "variant": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "additionalProperties": false }, "OfrepFailure": { "type": "object", "description": "An OFREP failure.", "properties": { "key": { "type": "string" }, "errorCode": { "type": "string", "enum": [ "PARSE_ERROR", "TARGETING_KEY_MISSING", "INVALID_CONTEXT", "GENERAL", "FLAG_NOT_FOUND" ] }, "errorDetails": { "type": "string" } }, "required": [ "errorCode" ], "additionalProperties": false }, "OfrepBulk": { "type": "object", "description": "OFREP `bulkEvaluationSuccess`.", "properties": { "flags": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/OfrepResult" }, { "$ref": "#/components/schemas/OfrepFailure" } ] } }, "metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "eventStreams": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "endpoint": { "type": "object", "properties": { "requestUri": { "type": "string" } }, "required": [ "requestUri" ], "additionalProperties": false }, "inactivityDelaySec": { "type": "integer", "minimum": 1 } }, "required": [ "type" ], "additionalProperties": false } } }, "required": [ "flags" ], "additionalProperties": false } } } }