{ "openapi": "3.1.0", "info": { "title": "stitchd-gateway API", "description": "REST gateway for the stitchd feature-flag and experimentation platform.\n\n## Auth Models\n- **SDK routes** (`/v1/environments/*/evaluate`, `/v1/environments/*/events`, `/v1/environments/*/segments/list-check`) require an `x-sdk-key` header.\n- **Admin / resource routes** require a `Bearer` JWT in the `Authorization` header.", "contact": { "name": "Stitchd" }, "license": { "name": "MIT", "identifier": "MIT" }, "version": "0.1.0" }, "paths": { "/v1/admin/orgs": { "post": { "tags": [ "admin" ], "summary": "`POST /v1/admin/orgs`", "operationId": "create_org", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrgBody" } } }, "required": true }, "responses": { "201": { "description": "Organisation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgJson" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller is not a system-org member" }, "502": { "description": "Management service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/admin/orgs/{org_id}/users": { "post": { "tags": [ "admin" ], "summary": "`POST /v1/admin/orgs/{org_id}/users` — seed the first user into a newly created org.", "operationId": "seed_user", "parameters": [ { "name": "org_id", "in": "path", "description": "Organisation ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeedUserBody" } } }, "required": true }, "responses": { "201": { "description": "User seeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserJson" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden — caller is not a system-org member" }, "502": { "description": "Management service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/auth/login": { "post": { "tags": [ "auth" ], "summary": "`POST /v1/auth/login`", "operationId": "login", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginBody" } } }, "required": true }, "responses": { "200": { "description": "Login successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginJson" } } } }, "401": { "description": "Invalid credentials" }, "502": { "description": "Auth service unavailable" } } } }, "/v1/environments/{env_id}/evaluate": { "post": { "tags": [ "flags" ], "summary": "`POST /v1/environments/{env_id}/evaluate`", "description": "Flag evaluation endpoint for SDK clients. Returns a simple evaluated flag result.", "operationId": "evaluate", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateRequest" } } }, "required": true }, "responses": { "200": { "description": "Evaluation result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EvaluateResponse" } } } }, "401": { "description": "Invalid or missing SDK key" } }, "security": [ { "sdk_key": [] } ] } }, "/v1/environments/{env_id}/event-definitions": { "get": { "tags": [ "events" ], "summary": "`GET /v1/environments/{env_id}/event-definitions`", "operationId": "list_event_definitions", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of event definitions" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_jwt": [] } ] }, "post": { "tags": [ "events" ], "summary": "`POST /v1/environments/{env_id}/event-definitions`", "operationId": "create_event_definition", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Event definition accepted" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/event-definitions/{def_id}": { "get": { "tags": [ "events" ], "summary": "`GET /v1/environments/{env_id}/event-definitions/{def_id}`", "operationId": "get_event_definition", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "def_id", "in": "path", "description": "Event definition key", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "description": "Unauthorized" }, "501": { "description": "Not implemented" } }, "security": [ { "bearer_jwt": [] } ] }, "put": { "tags": [ "events" ], "summary": "`PUT /v1/environments/{env_id}/event-definitions/{def_id}`", "operationId": "update_event_definition", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "def_id", "in": "path", "description": "Event definition key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Update accepted" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_jwt": [] } ] }, "delete": { "tags": [ "events" ], "summary": "`DELETE /v1/environments/{env_id}/event-definitions/{def_id}`", "operationId": "delete_event_definition", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "def_id", "in": "path", "description": "Event definition key", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Deleted" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/events": { "post": { "tags": [ "events" ], "summary": "`POST /v1/environments/{env_id}/events`", "operationId": "ingest_event", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkEventBody" } } }, "required": true }, "responses": { "202": { "description": "Event accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResponseJson" } } } }, "401": { "description": "Invalid or missing SDK key" }, "502": { "description": "Event service unavailable" } }, "security": [ { "sdk_key": [] } ] } }, "/v1/environments/{env_id}/events/batch": { "post": { "tags": [ "events" ], "summary": "`POST /v1/environments/{env_id}/events/batch`", "operationId": "ingest_batch_events", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Batch of events", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SdkEventBody" } } } }, "required": true }, "responses": { "202": { "description": "Events accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IngestResponseJson" } } } }, "401": { "description": "Invalid or missing SDK key" }, "502": { "description": "Event service unavailable" } }, "security": [ { "sdk_key": [] } ] } }, "/v1/environments/{env_id}/experiments": { "get": { "tags": [ "experiments" ], "summary": "`GET /v1/environments/{env_id}/experiments`", "operationId": "list_experiments", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of experiments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExperimentJson" } } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "post": { "tags": [ "experiments" ], "summary": "`POST /v1/environments/{env_id}/experiments`", "operationId": "create_experiment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateExperimentBody" } } }, "required": true }, "responses": { "201": { "description": "Experiment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/experiments/{experiment_id}": { "get": { "tags": [ "experiments" ], "summary": "`GET /v1/environments/{env_id}/experiments/{experiment_id}`", "operationId": "get_experiment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentJson" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Experiment not found" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "delete": { "tags": [ "experiments" ], "summary": "`DELETE /v1/environments/{env_id}/experiments/{experiment_id}`", "operationId": "delete_experiment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "patch": { "tags": [ "experiments" ], "summary": "`PATCH /v1/environments/{env_id}/experiments/{experiment_id}`", "operationId": "update_experiment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateExperimentBody" } } }, "required": true }, "responses": { "200": { "description": "Updated experiment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/experiments/{experiment_id}/iterations": { "get": { "tags": [ "experiments" ], "summary": "`GET /v1/environments/{env_id}/experiments/{experiment_id}/iterations`", "operationId": "list_iterations", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Experiment iterations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IterationJson" } } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/experiments/{experiment_id}/results": { "get": { "tags": [ "experiments" ], "summary": "`GET /v1/environments/{env_id}/experiments/{experiment_id}/results`", "operationId": "get_results", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Experiment results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentResultsJson" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Results not found" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/experiments/{experiment_id}/transitions": { "post": { "tags": [ "experiments" ], "summary": "`POST /v1/environments/{env_id}/experiments/{experiment_id}/transitions`", "operationId": "transition_experiment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "experiment_id", "in": "path", "description": "Experiment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransitionBody" } } }, "required": true }, "responses": { "200": { "description": "Experiment after transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExperimentJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Experimentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/segments": { "get": { "tags": [ "segments" ], "summary": "`GET /v1/environments/{env_id}/segments`", "operationId": "list_segments", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of segments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SegmentJson" } } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "post": { "tags": [ "segments" ], "summary": "`POST /v1/environments/{env_id}/segments`", "operationId": "create_segment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentCreateRequest" } } }, "required": true }, "responses": { "201": { "description": "Segment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/environments/{env_id}/segments/list-check": { "post": { "tags": [ "segments" ], "summary": "`POST /v1/environments/{env_id}/segments/list-check`", "operationId": "list_check_membership", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCheckRequest" } } }, "required": true }, "responses": { "200": { "description": "Membership result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCheckResponse" } } } }, "401": { "description": "Invalid or missing SDK key" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "sdk_key": [] } ] } }, "/v1/environments/{env_id}/segments/list-check/batch": { "post": { "tags": [ "segments" ], "summary": "`POST /v1/environments/{env_id}/segments/list-check/batch`", "operationId": "batch_list_check_membership", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Batch of membership checks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ListCheckRequest" } } } }, "required": true }, "responses": { "200": { "description": "Membership results", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ListCheckResponse" } } } } }, "401": { "description": "Invalid or missing SDK key" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "sdk_key": [] } ] } }, "/v1/environments/{env_id}/segments/{segment_id}": { "get": { "tags": [ "segments" ], "summary": "`GET /v1/environments/{env_id}/segments/{segment_key}`", "operationId": "get_segment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "description": "Segment key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Segment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentJson" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Segment not found" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "put": { "tags": [ "segments" ], "summary": "`PUT /v1/environments/{env_id}/segments/{segment_key}`", "operationId": "update_segment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "description": "Segment key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated segment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SegmentJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "delete": { "tags": [ "segments" ], "summary": "`DELETE /v1/environments/{env_id}/segments/{segment_key}`", "operationId": "delete_segment", "parameters": [ { "name": "env_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } }, { "name": "segment_id", "in": "path", "description": "Segment key", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Segment deleted" }, "401": { "description": "Unauthorized" }, "502": { "description": "Segmentation service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/experiments/{experiment_id}/recompute": { "post": { "tags": [ "crate::routes::stats" ], "summary": "`POST /v1/experiments/{experiment_id}/recompute`", "description": "Triggers an out-of-band stats recompute for an experiment.\nReturns 202 Accepted with a `job_id` for polling.", "operationId": "trigger_recompute", "parameters": [ { "name": "experiment_id", "in": "path", "description": "Experiment UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Recompute job accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecomputeJobJson" } } } }, "400": { "description": "Invalid experiment_id" }, "500": { "description": "Internal error" } } } }, "/v1/jobs/{job_id}": { "get": { "tags": [ "crate::routes::stats" ], "summary": "`GET /v1/jobs/{job_id}`", "description": "Returns the current status of a stats recompute job.", "operationId": "get_job_status", "parameters": [ { "name": "job_id", "in": "path", "description": "Job UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobStatusJson" } } } }, "404": { "description": "Job not found" }, "500": { "description": "Internal error" } } } }, "/v1/management/environments/{environment_id}/sdk-keys": { "post": { "tags": [ "admin" ], "summary": "`POST /v1/management/environments/{environment_id}/sdk-keys`", "operationId": "create_sdk_key", "parameters": [ { "name": "environment_id", "in": "path", "description": "Environment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "SDK key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SdkKeyJson" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "502": { "description": "Management service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/management/orgs/{org_id}/projects": { "post": { "tags": [ "admin" ], "summary": "`POST /v1/management/orgs/{org_id}/projects`", "operationId": "create_project", "parameters": [ { "name": "org_id", "in": "path", "description": "Organisation ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectBody" } } }, "required": true }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectJson" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "502": { "description": "Management service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/management/orgs/{org_id}/users": { "post": { "tags": [ "admin" ], "summary": "`POST /v1/management/orgs/{org_id}/users`", "operationId": "create_user", "parameters": [ { "name": "org_id", "in": "path", "description": "Organisation ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateUserBody" } } }, "required": true }, "responses": { "201": { "description": "User created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserJson" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "502": { "description": "Management service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/management/projects/{project_id}/environments": { "post": { "tags": [ "admin" ], "summary": "`POST /v1/management/projects/{project_id}/environments`", "operationId": "create_environment", "parameters": [ { "name": "project_id", "in": "path", "description": "Project ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvBody" } } }, "required": true }, "responses": { "201": { "description": "Environment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvJson" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "502": { "description": "Management service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/projects/{project_id}/flags": { "get": { "tags": [ "flags" ], "summary": "`GET /v1/projects/{project_id}/flags`", "operationId": "list_flags", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of flags", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/FlagJson" } } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Flag service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "post": { "tags": [ "flags" ], "summary": "`POST /v1/projects/{project_id}/flags`", "operationId": "create_flag", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagMutateRequest" } } }, "required": true }, "responses": { "201": { "description": "Flag created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Flag service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/projects/{project_id}/flags/{flag_id}": { "get": { "tags": [ "flags" ], "summary": "`GET /v1/projects/{project_id}/flags/{flag_id}`", "operationId": "get_flag", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "description": "Flag key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagJson" } } } }, "401": { "description": "Unauthorized" }, "404": { "description": "Flag not found" }, "502": { "description": "Flag service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "put": { "tags": [ "flags" ], "summary": "`PUT /v1/projects/{project_id}/flags/{flag_id}`", "operationId": "update_flag", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "description": "Flag key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagMutateRequest" } } }, "required": true }, "responses": { "200": { "description": "Updated flag", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FlagJson" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Flag service unavailable" } }, "security": [ { "bearer_jwt": [] } ] }, "delete": { "tags": [ "flags" ], "summary": "`DELETE /v1/projects/{project_id}/flags/{flag_id}`", "operationId": "delete_flag", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "description": "Flag key", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Flag deleted" }, "401": { "description": "Unauthorized" }, "502": { "description": "Flag service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/projects/{project_id}/flags/{flag_id}/hashing": { "put": { "tags": [ "flags" ], "summary": "`PUT /v1/projects/{project_id}/flags/{flag_id}/hashing`", "operationId": "update_flag_hashing", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "description": "Flag key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHashingBody" } } }, "required": true }, "responses": { "200": { "description": "Updated hashing configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHashingResponse" } } } }, "401": { "description": "Unauthorized" }, "502": { "description": "Flag service unavailable" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/projects/{project_id}/flags/{flag_id}/rules": { "put": { "tags": [ "flags" ], "summary": "`PUT /v1/projects/{project_id}/flags/{flag_id}/rules`", "operationId": "update_rules", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "description": "Flag key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Rules accepted for processing" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_jwt": [] } ] } }, "/v1/projects/{project_id}/flags/{flag_id}/variants": { "post": { "tags": [ "flags" ], "summary": "`POST /v1/projects/{project_id}/flags/{flag_id}/variants`", "operationId": "create_variant", "parameters": [ { "name": "project_id", "in": "path", "description": "Project / environment ID", "required": true, "schema": { "type": "string" } }, { "name": "flag_id", "in": "path", "description": "Flag key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "description": "Variant accepted for processing" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_jwt": [] } ] } } }, "components": { "schemas": { "BatchEventBody": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventBody" } } } }, "CreateEnvBody": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateExperimentBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "flag_key": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "variant_keys": { "type": [ "array", "null" ], "items": { "type": "string" } } } }, "CreateOrgBody": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateProjectBody": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" } } }, "CreateUserBody": { "type": "object", "required": [ "email", "display_name", "password" ], "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "org_role": { "type": [ "string", "null" ] }, "password": { "type": "string" } } }, "EnvJson": { "type": "object", "required": [ "environment_id", "environment_name" ], "properties": { "environment_id": { "type": "string" }, "environment_name": { "type": "string" } } }, "EvaluateRequest": { "type": "object", "required": [ "context_key", "context_type" ], "properties": { "context_key": { "type": "string" }, "context_type": { "type": "string" } } }, "EvaluateResponse": { "type": "object", "required": [ "evaluated" ], "properties": { "evaluated": { "type": "boolean" } } }, "EventBody": { "type": "object", "required": [ "metric_key", "context_type", "context_key", "value" ], "properties": { "context_key": { "type": "string" }, "context_type": { "type": "string" }, "metric_key": { "type": "string" }, "timestamp_ms": { "type": [ "integer", "null" ], "format": "int64" }, "value": { "type": [ "object", "null" ] } } }, "ExperimentJson": { "type": "object", "required": [ "id", "name", "description", "flag_key", "status", "variant_keys" ], "properties": { "description": { "type": "string" }, "flag_key": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string" }, "variant_keys": { "type": "array", "items": { "type": "string" } } } }, "ExperimentResultsJson": { "type": "object", "required": [ "experiment_id", "variant_results", "computed_at_ms", "is_stale", "next_run_at_ms", "computation_status" ], "properties": { "computation_status": { "type": "string" }, "computed_at_ms": { "type": "integer", "format": "int64" }, "experiment_id": { "type": "string" }, "is_stale": { "type": "boolean" }, "next_run_at_ms": { "type": "integer", "format": "int64" }, "variant_results": { "type": "array", "items": { "$ref": "#/components/schemas/VariantResultJson" } } } }, "FlagJson": { "type": "object", "description": "Lightweight JSON representation of a feature flag.", "required": [ "key", "enabled" ], "properties": { "enabled": { "type": "boolean" }, "key": { "type": "string" } } }, "FlagMutateRequest": { "type": "object", "description": "Request body for creating or updating a flag.", "required": [ "flag" ], "properties": { "enabled": { "type": [ "boolean", "null" ] }, "flag": { "type": [ "object", "null" ] }, "key": { "type": [ "string", "null" ] }, "version": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "HashingConfigItem": { "type": "object", "required": [ "parameter_key", "parameter_type", "order" ], "properties": { "order": { "type": "integer", "format": "int32" }, "parameter_key": { "type": "string" }, "parameter_type": { "type": "string" } } }, "HashingConfigJson": { "type": "object", "required": [ "parameter_key", "parameter_type", "order" ], "properties": { "order": { "type": "integer", "format": "int32" }, "parameter_key": { "type": "string" }, "parameter_type": { "type": "string" } } }, "IngestResponseJson": { "type": "object", "required": [ "accepted_count", "rejected_keys" ], "properties": { "accepted_count": { "type": "integer", "format": "int32", "minimum": 0 }, "rejected_keys": { "type": "array", "items": { "type": "string" } } } }, "IterationJson": { "type": "object", "required": [ "id", "experiment_id", "iteration_number", "started_at_ms", "ended_at_ms", "traffic_allocation" ], "properties": { "ended_at_ms": { "type": "integer", "format": "int64" }, "experiment_id": { "type": "string" }, "id": { "type": "string" }, "iteration_number": { "type": "integer", "format": "int32" }, "started_at_ms": { "type": "integer", "format": "int64" }, "traffic_allocation": { "type": "number", "format": "double" } } }, "JobStatusJson": { "type": "object", "required": [ "job_id", "status", "started_at_ms", "completed_at_ms", "error" ], "properties": { "completed_at_ms": { "type": "integer", "format": "int64" }, "error": { "type": "string" }, "job_id": { "type": "string" }, "started_at_ms": { "type": "integer", "format": "int64" }, "status": { "type": "string" } } }, "ListCheckRequest": { "type": "object", "required": [ "segment_key", "context_key", "context_type" ], "properties": { "context_key": { "type": "string" }, "context_type": { "type": "string" }, "segment_key": { "type": "string" } } }, "ListCheckResponse": { "type": "object", "required": [ "is_member" ], "properties": { "is_member": { "type": "boolean" } } }, "LoginBody": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string" }, "org_id": { "type": [ "string", "null" ] }, "password": { "type": "string" } } }, "LoginJson": { "type": "object", "required": [ "access_token", "refresh_token", "expires_in", "user_id", "org_id" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64" }, "org_id": { "type": "string" }, "refresh_token": { "type": "string" }, "user_id": { "type": "string" } } }, "OrgJson": { "type": "object", "required": [ "org_id", "org_name" ], "properties": { "org_id": { "type": "string" }, "org_name": { "type": "string" } } }, "ProjectJson": { "type": "object", "required": [ "project_id", "project_name" ], "properties": { "project_id": { "type": "string" }, "project_name": { "type": "string" } } }, "RecomputeJobJson": { "type": "object", "required": [ "job_id", "status", "created_at_ms" ], "properties": { "created_at_ms": { "type": "integer", "format": "int64" }, "job_id": { "type": "string" }, "status": { "type": "string" } } }, "SdkEventBody": { "type": "object", "required": [ "metric_key", "context_key", "context_type", "value" ], "properties": { "context_key": { "type": "string" }, "context_type": { "type": "string" }, "metric_key": { "type": "string" }, "timestamp_ms": { "type": [ "integer", "null" ], "format": "int64" }, "value": { "type": [ "object", "null" ] } } }, "SdkKeyJson": { "type": "object", "required": [ "sdk_key_id", "raw_key" ], "properties": { "raw_key": { "type": "string" }, "sdk_key_id": { "type": "string" } } }, "SeedUserBody": { "type": "object", "required": [ "email" ], "properties": { "display_name": { "type": [ "string", "null" ], "description": "Optional for existing users — omit or send null/empty when adding a\nplatform user who already has a display name." }, "email": { "type": "string" }, "org_role": { "type": [ "string", "null" ] }, "password": { "type": [ "string", "null" ], "description": "Optional for existing users — omit or send null/empty. The backend\nskips user creation and just adds the org membership." } } }, "SegmentCreateRequest": { "type": "object", "properties": { "context_type": { "type": [ "string", "null" ] }, "key": { "type": [ "string", "null" ] } } }, "SegmentJson": { "type": "object", "required": [ "key", "context_type", "kind" ], "properties": { "context_type": { "type": "string" }, "key": { "type": "string" }, "kind": { "type": "string" } } }, "TransitionBody": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } }, "UpdateExperimentBody": { "type": "object", "properties": { "description": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "variant_keys": { "type": [ "array", "null" ], "items": { "type": "string" } }, "version": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "UpdateHashingBody": { "type": "object", "required": [ "configs" ], "properties": { "configs": { "type": "array", "items": { "$ref": "#/components/schemas/HashingConfigItem" } } } }, "UpdateHashingResponse": { "type": "object", "required": [ "flag", "configs" ], "properties": { "configs": { "type": "array", "items": { "$ref": "#/components/schemas/HashingConfigJson" } }, "flag": { "$ref": "#/components/schemas/FlagJson" } } }, "UserJson": { "type": "object", "required": [ "user_id", "email", "display_name" ], "properties": { "display_name": { "type": "string" }, "email": { "type": "string" }, "user_id": { "type": "string" } } }, "VariantResultJson": { "type": "object", "required": [ "variant_key", "participant_count" ], "properties": { "participant_count": { "type": "integer", "format": "int64", "minimum": 0 }, "variant_key": { "type": "string" } } } }, "securitySchemes": { "bearer_jwt": { "type": "http", "scheme": "bearer" }, "sdk_key": { "type": "apiKey", "in": "header", "name": "x-sdk-key" } } } }