{ "openapi": "3.0.3", "info": { "title": "Organization API", "description": "The Organization API provides endpoints for managing epilot tenant organizations.\n\n## Overview\n\nThis API allows you to:\n- **Retrieve organization details** - Get information about the current organization or a specific organization by ID\n- **Update organization profiles** - Modify organization name, contact information, address, and branding assets\n- **Manage organization settings** - Configure organization-wide settings such as feature flags and preferences\n- **Branding configuration** - Set organization logos, email signatures, and style settings\n\n## Organization Types\n\nOrganizations can be configured as:\n- **Production** - Live production environments for real business operations\n- **Sandbox** - Test environments linked to a parent production organization\n- **Preview** - Temporary copies of a production organization, used to preview configuration changes\n", "version": "1.1.0" }, "tags": [ { "name": "Organization", "description": "Endpoints for managing organization profiles and information.\n\nOrganizations represent tenant accounts in the epilot platform. Each organization has:\n- Basic profile information (name, contact details, address)\n- Branding assets (logo, email signature)\n- Configuration settings\n- Usage type (Production, Sandbox or Preview)\n" }, { "name": "Organization Settings", "description": "Endpoints for managing organization-wide configuration settings.\n\nSettings are stored as key-value pairs and can include:\n- Feature flags (e.g., double_opt_in)\n- Integration configurations\n- Platform preferences\n\nSettings values can be strings, numbers, booleans, arrays, or objects.\n" }, { "name": "Feature Settings", "description": "Feature flag metadata for the organization settings page.\n\nThis metadata is used by frontend applications to render feature toggles\nwithout hardcoding titles, descriptions, badges, and visibility rules in the UI.\n" }, { "name": "Announcements", "description": "Platform announcements shown as a non-blocking portal banner, e.g. subprocessor change notices.\n\nAnnouncements are managed internally (admin portal) and acknowledged by organization admins.\nEach organization acknowledges an announcement at most once (first acknowledgement wins).\n" } ], "security": [ { "EpilotAuth": [] } ], "paths": { "/v2/organization/current": { "get": { "operationId": "getCurrentOrganization", "x-epilot-permissions": [ { "access": "org" } ], "summary": "getCurrentOrganization", "description": "Retrieves the organization associated with the authenticated user's current session.\n\nThis endpoint is useful for fetching organization details without knowing the organization ID,\nas it automatically resolves the organization from the authentication token.\n", "tags": [ "Organization" ], "responses": { "200": { "description": "The organization associated with the current authenticated user", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" }, "example": { "id": "739224", "name": "Epilot", "email": "contact@epilot.cloud", "phone": "+49123456789", "website": "https://epilot.cloud", "address": { "country": "Germany", "city": "Cologne", "postal_code": "50667", "street": "Im Mediapark", "street_number": "8a" }, "organization_use": "Production", "created_date": "2021-01-15T10:30:00Z", "logo_url": "https://epilot-playground-organization-data.s3.eu-central-1.amazonaws.com/epilot-logo.png", "signature": "
Best regards,
The epilot Team
Best regards,
The epilot Team
Kind regards,
The epilot Team
Thanks
", "nullable": true }, "is_unlicensed_org": { "type": "boolean", "example": false, "nullable": true, "deprecated": true }, "style": { "type": "object", "description": "Organization style setting (e.g. font setting)", "additionalProperties": true, "nullable": true, "deprecated": true }, "type": { "type": "string", "deprecated": true, "enum": [ "Vendor", "Partner" ], "nullable": true }, "symbol": { "deprecated": true, "type": "string", "example": "EPI", "nullable": true }, "pricing_tier": { "deprecated": true, "description": "Deprecated - Please use pricing tier api", "type": "string", "example": "professional", "nullable": true }, "free_user_limit": { "deprecated": true, "type": "number", "example": 50, "nullable": true }, "tags": { "type": "array", "description": "Labels/tags associated with the organization for categorization and filtering.\nUsed internally to classify organizations (e.g., \"enterprise\", \"beta-tester\", \"test org\").\n", "items": { "type": "string", "example": "test org" }, "nullable": true } } }, "Settings": { "type": "object", "description": "A key-value map of all organization settings.\nKeys are setting identifiers and values can be any valid JSON type.\n", "additionalProperties": true, "example": { "double_opt_in": { "enabled": true }, "email_tracking": { "enabled": true, "track_opens": true }, "default_language": "de" } }, "SettingsValue": { "description": "The value of an organization setting.\nCan be any valid JSON type: string, number, boolean, array, or object.\n", "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ], "example": { "enabled": true } }, "FeatureSettings": { "type": "object", "description": "Feature settings metadata served to frontend applications.", "required": [ "version", "feature_flags" ], "properties": { "version": { "type": "string", "description": "Schema version for backwards compatibility", "example": "1.0.0" }, "feature_flags": { "type": "array", "description": "Feature flag metadata for the settings page", "items": { "$ref": "#/components/schemas/FeatureFlagMetadata" } } } }, "FeatureFlagMetadata": { "type": "object", "description": "Metadata for a single feature flag toggle", "required": [ "feature_name", "visibility_rules" ], "properties": { "feature_name": { "type": "string", "description": "Unique identifier matching the organization setting key", "example": "canary" }, "title": { "$ref": "#/components/schemas/I18nString" }, "description": { "$ref": "#/components/schemas/I18nString" }, "badge": { "type": "string", "description": "Badge label shown next to the feature toggle", "enum": [ "alpha", "beta", "new", "advanced", "experiment", "deprecated" ] }, "confetti": { "type": "boolean", "description": "Whether to show confetti animation when enabled" }, "one_way": { "type": "boolean", "description": "Whether the toggle can only be turned on (not off)" }, "reverse_checked": { "type": "boolean", "description": "Whether the toggle value is inverted (checked = disabled)" }, "is_visible_for_partner": { "type": "boolean", "description": "Whether this feature is visible for partner organizations" }, "visibility_rules": { "type": "array", "description": "Rules that must ALL pass for this feature to be visible (implicit AND)", "items": { "$ref": "#/components/schemas/VisibilityRule" } } } }, "I18nString": { "type": "object", "description": "Internationalized string with a translation key and optional default value", "required": [ "key" ], "properties": { "key": { "type": "string", "description": "Translation key for i18n lookup", "example": "canary_setting.title" }, "default_value": { "type": "string", "description": "Fallback value when translation is not available", "example": "Canary Updates" } } }, "VisibilityRule": { "type": "object", "description": "A rule that determines feature visibility. Rules are combined with AND logic\nat the top level. Supports boolean combinators (and, or, not) for complex logic.\n", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "The rule type discriminator", "enum": [ "always", "never", "advanced_mode", "pricing_tier", "pricing_tier_class", "production_org", "feature_flag", "permission", "setting_enabled", "flag_enabled", "not", "and", "or" ] }, "setting_key": { "type": "string", "description": "Setting key for pricing_tier and setting_enabled rules" }, "flag_name": { "type": "string", "description": "Flag name for feature_flag and flag_enabled rules" }, "pricing_tier_classes": { "type": "array", "description": "Pricing tier class names matched (word-boundary, case-insensitive) for pricing_tier_class rules", "items": { "type": "string" }, "example": [ "enterprise", "professional" ] }, "action": { "type": "string", "description": "Permission action for permission rules" }, "resource": { "type": "string", "description": "Optional resource for permission rules" }, "rule": { "$ref": "#/components/schemas/VisibilityRule" }, "rules": { "type": "array", "description": "Child rules for and/or combinators", "items": { "$ref": "#/components/schemas/VisibilityRule" } } } }, "AnnouncementType": { "type": "string", "enum": [ "subprocessor_change" ] }, "AnnouncementMessage": { "type": "object", "required": [ "de" ], "properties": { "de": { "type": "string", "minLength": 1, "example": "Wir haben unsere Liste der Subdienstleister aktualisiert (gültig ab 01.11.2026). Bitte prüfe die Änderungen." }, "en": { "type": "string", "example": "We have updated our list of subprocessors (effective 01.11.2026). Please review the changes." } } }, "Announcement": { "type": "object", "required": [ "id", "type", "message", "link_url", "list_version", "effective_date", "window_days", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/AnnouncementType" }, "message": { "$ref": "#/components/schemas/AnnouncementMessage" }, "link_url": { "type": "string" }, "list_version": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "window_days": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "description": "Internal caller that created the announcement (not returned to customers)" }, "updated_at": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time" }, "published_by": { "type": "string", "description": "Internal caller that published the announcement (not returned to customers)" }, "expires_at": { "type": "string", "format": "date-time", "description": "published_at + window_days" }, "archived_at": { "type": "string", "format": "date-time" }, "archived_by": { "type": "string" }, "materialized_at": { "type": "string", "format": "date-time", "description": "When the daily job wrote expired/superseded records after the window closed" } } }, "AnnouncementOrganizationStatusValue": { "type": "string", "enum": [ "acknowledged", "pending", "expired", "superseded" ] }, "AnnouncementOrganizationStatus": { "type": "object", "required": [ "announcement_id", "org_id", "status", "list_version" ], "properties": { "announcement_id": { "type": "string" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "status": { "$ref": "#/components/schemas/AnnouncementOrganizationStatusValue" }, "acknowledged_by": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" } } }, "acknowledged_at": { "type": "string", "format": "date-time" }, "portal": { "type": "string", "example": "360" }, "list_version": { "type": "string" }, "recorded_at": { "type": "string", "format": "date-time", "description": "When the record was written (acknowledgement or materialization by the daily job)" } } }, "ActiveAnnouncementResponse": { "type": "object", "required": [ "announcement", "can_acknowledge" ], "properties": { "announcement": { "allOf": [ { "$ref": "#/components/schemas/Announcement" } ], "nullable": true }, "can_acknowledge": { "type": "boolean", "description": "Whether the caller may acknowledge (organization:edit)" } } } } }, "servers": [ { "url": "https://organization-v2.sls.epilot.io" } ] }