openapi: 3.0.3 info: title: Unleash Admin Addons Instance Admin API version: 7.4.1 description: Create, update, and delete [Unleash addons](https://docs.getunleash.io/addons). servers: - url: https://app.unleash-instance.example.com description: Your Unleash instance (replace with your actual URL) security: - apiKey: [] - bearerToken: [] tags: - name: Instance Admin description: Instance admin endpoints used to manage the Unleash instance itself. paths: /api/admin/logins: get: tags: - Instance Admin operationId: getLoginHistory responses: '200': description: loginHistorySchema content: application/json: schema: $ref: '#/components/schemas/loginHistorySchema' text/csv: schema: type: string '204': description: This response has no body. '401': description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`. content: application/json: schema: type: object properties: id: type: string example: 9c40958a-daac-400e-98fb-3bb438567008 description: The ID of the error instance name: type: string example: AuthenticationRequired description: The name of the error kind message: type: string example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login. description: A description of what went wrong. '404': description: The requested resource was not found. content: application/json: schema: type: object properties: id: type: string example: 9c40958a-daac-400e-98fb-3bb438567008 description: The ID of the error instance name: type: string example: NotFoundError description: The name of the error kind message: type: string example: Could not find the addon with ID "12345". description: A description of what went wrong. description: '**Enterprise feature** Returns **all** login events in the Unleash system. You can optionally get them in CSV format by specifying the `Accept` header as `text/csv`.' summary: Get All Login Events. /api/admin/license/check: get: tags: - Instance Admin operationId: checkLicense summary: Validates the Unleash License. description: '**Enterprise feature** Validates the Unleash license.' responses: '200': description: licenseCheckSchema content: application/json: schema: $ref: '#/components/schemas/licenseCheckSchema' /api/admin/license: get: tags: - Instance Admin summary: Reads the Unleash License. description: '**Enterprise feature** Reads the Unleash license. Only available for self-hosted Enterprise customers.' operationId: readLicense responses: '200': description: licenseReadSchema content: application/json: schema: $ref: '#/components/schemas/licenseReadSchema' post: tags: - Instance Admin operationId: updateLicense summary: Set a New Unleash License. description: '**Enterprise feature** Set a new Unleash license. Only available for self-hosted Enterprise customers.' requestBody: description: licenseUpdateSchema required: true content: application/json: schema: $ref: '#/components/schemas/licenseUpdateSchema' responses: '201': headers: location: description: The location of the newly created resource. schema: type: string format: uri description: The resource was successfully created. content: application/json: schema: $ref: '#/components/schemas/licenseReadSchema' '400': description: The request data does not match what we expect. content: application/json: schema: type: object properties: id: type: string example: 9c40958a-daac-400e-98fb-3bb438567008 description: The ID of the error instance name: type: string example: ValidationError description: The name of the error kind message: type: string example: The request payload you provided doesn't conform to the schema. The .parameters property should be object. You sent []. description: A description of what went wrong. '401': description: Authorization information is missing or invalid. Provide a valid API token as the `authorization` header, e.g. `authorization:*.*.my-admin-token`. content: application/json: schema: type: object properties: id: type: string example: 9c40958a-daac-400e-98fb-3bb438567008 description: The ID of the error instance name: type: string example: AuthenticationRequired description: The name of the error kind message: type: string example: You must log in to use Unleash. Your request had no authorization header, so we could not authorize you. Try logging in at /auth/simple/login. description: A description of what went wrong. '403': description: The provided user credentials are valid, but the user does not have the necessary permissions to perform this operation content: application/json: schema: type: object properties: id: type: string example: 9c40958a-daac-400e-98fb-3bb438567008 description: The ID of the error instance name: type: string example: NoAccessError description: The name of the error kind message: type: string example: You need the "UPDATE_ADDON" permission to perform this action in the "development" environment. description: A description of what went wrong. '415': description: The operation does not support request payloads of the provided type. Please ensure that you're using one of the listed payload types and that you have specified the right content type in the "content-type" header. content: application/json: schema: type: object properties: id: type: string example: 9c40958a-daac-400e-98fb-3bb438567008 description: The ID of the error instance name: type: string example: ContentTypeerror description: The name of the error kind message: type: string example: We do not accept the content-type you provided (application/xml). Try using one of the content-types we do accept instead (application/json) and make sure the body is in the corresponding format. description: A description of what went wrong. /api/admin/instance-admin/statistics/csv: get: tags: - Instance Admin summary: Instance Usage Statistics description: Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc. operationId: getInstanceAdminStatsCsv responses: '200': description: instanceAdminStatsSchemaCsv content: text/csv: example: '"OIDCenabled","SAMLenabled","passwordAuthEnabled","SCIMenabled","clientApps","contextFields","environments","featureExports","featureImports","featureToggles","archivedFeatureToggles","groups","instanceId","projects","roles","customRootRoles","customRootRolesInUse","segments","strategies","sum","timestamp","users","licensedUsers","serviceAccounts","apiTokens","versionEnterprise","versionOSS","activeUsers","productionChanges","previousDayMetricsBucketsCount","maxEnvironmentStrategies","maxConstraints","maxConstraintValues","releaseTemplates","releasePlans","edgeInstanceUsage","readOnlyUsers" true,false,true,false,"[{""range"":""allTime"",""count"":15},{""range"":""30d"",""count"":9},{""range"":""7d"",""count"":5}]",6,2,0,0,29,10,3,"ed3861ae-78f9-4e8c-8e57-b57efc15f82b",4,5,2,1,2,8,"some-sha256-hash","2023-07-12T10:00:00.000Z",10,12,2,"{}","5.1.7","5.1.7","{""last90"":15,""last60"":12,""last30"":10,""last7"":5}","{""last30"":100,""last60"":200,""last90"":200}","{""variantCount"":100,""enabledCount"":200}",20,17,123,3,5,"{""2022-06"":2.345,""2022-07"":2.567,""2022-08"":2.789}",4' schema: type: string /api/admin/instance-admin/statistics: get: tags: - Instance Admin operationId: getInstanceAdminStats summary: Instance Usage Statistics description: Provides statistics about various features of Unleash to allow for reporting of usage for self-hosted customers. The response contains data such as the number of users, groups, features, strategies, versions, etc. responses: '200': description: instanceAdminStatsSchema content: application/json: schema: $ref: '#/components/schemas/instanceAdminStatsSchema' components: schemas: licenseReadSchema: description: A model representing a license response. type: object additionalProperties: false required: - isValid properties: token: description: The actual license token. type: string isValid: description: Whether the license is valid or not. type: boolean customer: description: Name of the customer that owns the license. This is the name of the company that purchased the license. type: string type: description: Type of license. type: string instanceName: description: Name of the Unleash instance where this license is valid. type: string instanceId: description: Identifier of the Unleash instance where this license is valid. type: string plan: description: Name of plan that the license is for. type: string resources: type: object description: The resources available in the license. additionalProperties: false properties: seats: description: Number of seats in the license. type: number releaseTemplates: description: Number of release templates in the license. type: number edgeInstances: description: Number of Edge instances in the license. type: number readOnlyUsers: description: Number of read-only users in the license. type: number expireAt: description: Date when the license expires. type: string format: date-time example: '2023-07-31T13:33:02Z' issuedAt: description: Date when the license was issued. type: string format: date-time example: '2023-07-31T13:33:02Z' loginHistorySchema: description: A response model with a list of login events. type: object additionalProperties: false required: - events properties: events: type: array description: A list of login events items: $ref: '#/components/schemas/loginEventSchema' licenseUpdateSchema: description: A model representing a set license token. type: object additionalProperties: false required: - token properties: token: description: The actual license token. type: string loginEventSchema: description: A model representing a single login event. type: object additionalProperties: false required: - id properties: id: description: The event's ID. Event IDs are incrementing integers. In other words, a more recent event will always have a higher ID than an older event. type: integer minimum: 1 example: 13 username: description: The username of the user that attempted to log in. Will return "Incorrectly configured provider" when attempting to log in using a misconfigured provider. type: string example: admin auth_type: description: The authentication type used to log in. example: simple type: string created_at: description: The date and time of when the login was attempted. type: string format: date-time example: '2023-03-01T12:04:26.061Z' successful: description: Whether the login was successful or not. type: boolean example: true ip: description: The IP address of the client that attempted to log in. type: string nullable: true example: ::ffff:127.0.0.1 failure_reason: description: The reason for the login failure. This property is only present if the login was unsuccessful. type: string nullable: true example: No user found instanceAdminStatsSchema: type: object additionalProperties: false description: Information about an instance and statistics about usage of various features of Unleash required: - instanceId properties: instanceId: type: string description: A unique identifier for this instance. Generated by the database migration scripts at first run. Typically a UUID. example: ed3861ae-78f9-4e8c-8e57-b57efc15f82b timestamp: type: string format: date-time nullable: true description: When these statistics were produced example: '2023-06-12T12:25:06Z' versionOSS: type: string description: The version of Unleash OSS that is bundled in this instance example: 5.1.7 versionEnterprise: type: string description: The version of Unleash Enterprise that is bundled in this instance example: 5.1.7 users: type: integer description: The number of users this instance has example: 8 minimum: 0 previousDayMetricsBucketsCount: type: object description: 'The number client metrics buckets records recorded in the previous day. # features * # apps * # envs * # hours with metrics' properties: enabledCount: type: integer description: The number of enabled/disabled metrics buckets recorded in the previous day example: 10 minimum: 0 variantCount: type: integer description: The number of variant metrics buckets recorded in the previous day example: 10 minimum: 0 activeUsers: type: object description: The number of active users in the last 7, 30 and 90 days properties: last7: type: integer description: The number of active users in the last 7 days example: 5 minimum: 0 last30: type: integer description: The number of active users in the last 30 days example: 10 minimum: 0 last60: type: integer description: The number of active users in the last 60 days example: 12 minimum: 0 last90: type: integer description: The number of active users in the last 90 days example: 15 minimum: 0 licensedUsers: type: integer description: The number of users who had access to Unleash within the last 30 days, including those who may have been deleted during this period. example: 10 minimum: 0 productionChanges: type: object description: The number of changes to the production environment in the last 30, 60 and 90 days properties: last30: type: integer description: The number of changes in production in the last 30 days example: 10 minimum: 0 last60: type: integer description: The number of changes in production in the last 60 days example: 12 minimum: 0 last90: type: integer description: The number of changes in production in the last 90 days example: 15 minimum: 0 featureToggles: type: integer description: The number of feature-toggles this instance has example: 47 minimum: 0 projects: type: integer description: The number of projects defined in this instance. example: 3 minimum: 0 contextFields: type: integer description: The number of context fields defined in this instance. example: 7 minimum: 0 roles: type: integer description: The number of roles defined in this instance example: 5 minimum: 0 groups: type: integer description: The number of groups defined in this instance example: 12 minimum: 0 environments: type: integer description: The number of environments defined in this instance example: 3 minimum: 0 segments: type: integer description: The number of segments defined in this instance example: 19 minimum: 0 strategies: type: integer description: The number of strategies defined in this instance example: 8 minimum: 0 SAMLenabled: type: boolean description: Whether or not SAML authentication is enabled for this instance example: false OIDCenabled: type: boolean description: Whether or not OIDC authentication is enabled for this instance example: true clientApps: type: array description: A count of connected applications in the last week, last month and all time since last restart items: type: object description: An entry describing how many client applications has been observed over the defined range properties: range: type: string description: A description of a time range enum: - allTime - 30d - 7d example: 30d count: type: integer description: The number of client applications that have been observed in this period example: 1 featureExports: type: integer description: The number of export operations on this instance example: 0 minimum: 0 featureImports: type: integer description: The number of import operations on this instance example: 0 minimum: 0 apiTokens: type: object description: The number of API tokens in Unleash, split by type properties: admin: type: integer description: The number of admin tokens. minimum: 0 example: 5 client: type: integer description: The number of client tokens. minimum: 0 example: 5 frontend: type: integer description: The number of frontend tokens. minimum: 0 example: 5 maxEnvironmentStrategies: type: integer minimum: 0 example: 3 description: The highest number of strategies used on a single feature flag in a single environment. maxConstraints: type: integer minimum: 0 example: 4 description: The highest number of constraints used on a single strategy. maxConstraintValues: type: integer minimum: 0 example: 17 description: The highest number of constraint values used on a single constraint. releaseTemplates: type: integer minimum: 0 example: 2 description: The number of release templates in this instance releasePlans: type: integer minimum: 0 example: 1 description: The number of release plans in this instance edgeInstanceUsage: type: object description: The average number of edge instances, per month, in the last 12 months, rounded to 3 decimal places additionalProperties: type: number minimum: 0 example: 2025-09: 2.25 2025-08: 1.75 2024-10: 0.45 readOnlyUsers: type: integer minimum: 0 example: 1 description: The number of ReadOnly users in this instance sum: type: string description: A SHA-256 checksum of the instance statistics to be used to verify that the data in this object has not been tampered with example: b023323477abb1eb145bebf3cdb30a1c2063e3edc1f7ae474ed8ed6c80de9a3b licenseCheckSchema: description: A model representing a license check response. type: object additionalProperties: false required: - isValid properties: isValid: description: Whether or not the current Unleash license is considered valid type: boolean message: description: Message describing the current state of the Unleash license type: string example: Your license expired 3 days ago messageType: description: Type of messages, whether it is an informative or a warning type: string example: info enum: - info - warning - error securitySchemes: apiKey: type: apiKey in: header name: Authorization description: API key needed to access this API bearerToken: type: http scheme: bearer description: API key needed to access this API, in Bearer token format