openapi: 3.0.3
info:
  title: Gravitee.io APIM Management API
  description: |-
    The Gravitee API Management (APIM) Management API is the administrative
    control plane for the Gravitee platform. It exposes endpoints to create
    and deploy APIs (both v2 "Gravitee definition v2" and v4 message-oriented
    APIs), manage plans, applications, subscriptions, API products,
    analytics, logs, users, plugins, UI customization, environments, and
    organization-level installation.

    This consolidated specification is synthesized from the upstream v2
    OpenAPI fragments in `gravitee-apim-rest-api-management-v2-rest`
    (`openapi-apis.yaml`, `openapi-environments.yaml`,
    `openapi-analytics.yaml`, `openapi-api-products.yaml`,
    `openapi-installation.yaml`, `openapi-plugins.yaml`,
    `openapi-users.yaml`, `openapi-logs.yaml`, `openapi-ui.yaml`).
  contact:
    name: GraviteeSource Team
    url: https://gravitee.io
    email: team-apim@graviteesource.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 2.0.0
servers:
  - url: https://{host}/management/v2
    description: APIM Management API v2 - default base URL
    variables:
      host:
        default: apim.example.com
        description: Hostname of the Gravitee APIM Management API
  - url: https://{host}/management/v2/organizations/{orgId}
    description: APIM Management API v2 - per-organization base URL
    variables:
      host:
        default: apim.example.com
      orgId:
        default: DEFAULT
security:
  - BasicAuth: []
  - CookieAuth: []
  - BearerAuth: []
tags:
  - name: APIs
    description: Manage APIs (v2 and v4 message-oriented APIs)
  - name: API Products
    description: Bundle one or more APIs into a publishable API product
  - name: Plans
    description: Manage plans (Keyless, API Key, OAuth2, JWT, mTLS, Push)
  - name: Applications
    description: Manage consumer applications
  - name: Subscriptions
    description: Manage subscriptions between applications and plans
  - name: Analytics
    description: Query analytics, time-series, and dashboards
  - name: Logs
    description: Search request and error logs
  - name: Environments
    description: Manage environments and their configuration
  - name: Installation
    description: Manage organizations, environments, and platform installation
  - name: Plugins
    description: Discover policies, endpoints, entrypoints, and resources installed in the gateway
  - name: Users
    description: Manage Gravitee users
  - name: UI
    description: Customize developer portal and console themes
paths:
  /environments/{envId}/apis:
    get:
      tags: [APIs]
      operationId: listApis
      summary: List APIs in an Environment
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: query
          name: page
          schema: { type: integer, default: 1 }
        - in: query
          name: perPage
          schema: { type: integer, default: 10 }
      responses:
        '200':
          description: A page of APIs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApisPage'
    post:
      tags: [APIs]
      operationId: createApi
      summary: Create an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApi'
      responses:
        '201':
          description: API created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api'
  /environments/{envId}/apis/_import/swagger:
    post:
      tags: [APIs]
      operationId: importSwaggerApi
      summary: Import an API from an OpenAPI/Swagger Document
      parameters:
        - $ref: '#/components/parameters/EnvId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportSwaggerDescriptor'
      responses:
        '201':
          description: API imported
  /environments/{envId}/apis/_import/definition:
    post:
      tags: [APIs]
      operationId: importApiDefinition
      summary: Import an API From a Gravitee Definition
      parameters:
        - $ref: '#/components/parameters/EnvId'
      requestBody:
        required: true
        content:
          application/json: { schema: { type: object } }
      responses:
        '201': { description: API imported }
  /environments/{envId}/apis/_search:
    post:
      tags: [APIs]
      operationId: searchApis
      summary: Search APIs by Query
      parameters:
        - $ref: '#/components/parameters/EnvId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query: { type: string }
      responses:
        '200': { description: Matching APIs }
  /environments/{envId}/apis/{apiId}:
    get:
      tags: [APIs]
      operationId: getApi
      summary: Get an API by Identifier
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '200':
          description: The API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Api'
    put:
      tags: [APIs]
      operationId: updateApi
      summary: Update an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Api'
      responses:
        '200': { description: API updated }
    delete:
      tags: [APIs]
      operationId: deleteApi
      summary: Delete an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '204': { description: API deleted }
  /environments/{envId}/apis/{apiId}/_deploy:
    post:
      tags: [APIs]
      operationId: deployApi
      summary: Deploy an API to the Gateway
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '202': { description: Deployment requested }
  /environments/{envId}/apis/{apiId}/_start:
    post:
      tags: [APIs]
      operationId: startApi
      summary: Start an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '204': { description: API started }
  /environments/{envId}/apis/{apiId}/_stop:
    post:
      tags: [APIs]
      operationId: stopApi
      summary: Stop an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '204': { description: API stopped }
  /environments/{envId}/apis/{apiId}/plans:
    get:
      tags: [Plans]
      operationId: listApiPlans
      summary: List Plans on an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '200': { description: Plans page }
    post:
      tags: [Plans]
      operationId: createApiPlan
      summary: Create a Plan on an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Plan'
      responses:
        '201': { description: Plan created }
  /environments/{envId}/apis/{apiId}/plans/{planId}:
    get:
      tags: [Plans]
      operationId: getApiPlan
      summary: Get a Plan by Identifier
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
        - in: path
          name: planId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The plan }
    put:
      tags: [Plans]
      operationId: updateApiPlan
      summary: Update a Plan
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
        - in: path
          name: planId
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Plan'
      responses:
        '200': { description: Plan updated }
  /environments/{envId}/apis/{apiId}/plans/{planId}/_publish:
    post:
      tags: [Plans]
      operationId: publishApiPlan
      summary: Publish a Plan
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
        - in: path
          name: planId
          required: true
          schema: { type: string }
      responses:
        '204': { description: Plan published }
  /environments/{envId}/apis/{apiId}/plans/{planId}/_close:
    post:
      tags: [Plans]
      operationId: closeApiPlan
      summary: Close a Plan
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
        - in: path
          name: planId
          required: true
          schema: { type: string }
      responses:
        '204': { description: Plan closed }
  /environments/{envId}/apis/{apiId}/subscriptions:
    get:
      tags: [Subscriptions]
      operationId: listApiSubscriptions
      summary: List Subscriptions for an API
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - $ref: '#/components/parameters/ApiId'
      responses:
        '200': { description: Subscriptions page }
  /environments/{envId}/applications:
    get:
      tags: [Applications]
      operationId: listApplications
      summary: List Applications
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Applications page }
    post:
      tags: [Applications]
      operationId: createApplication
      summary: Create an Application
      parameters:
        - $ref: '#/components/parameters/EnvId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
      responses:
        '201': { description: Application created }
  /environments/{envId}/applications/{applicationId}:
    get:
      tags: [Applications]
      operationId: getApplication
      summary: Get an Application by Identifier
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: applicationId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The application }
  /environments/{envId}/subscriptions:
    get:
      tags: [Subscriptions]
      operationId: listSubscriptions
      summary: List Subscriptions
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Subscriptions page }
    post:
      tags: [Subscriptions]
      operationId: createSubscription
      summary: Create a Subscription
      parameters:
        - $ref: '#/components/parameters/EnvId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Subscription'
      responses:
        '201': { description: Subscription created }
  /environments/{envId}/subscriptions/{subscriptionId}:
    get:
      tags: [Subscriptions]
      operationId: getSubscription
      summary: Get a Subscription
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: subscriptionId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The subscription }
  /environments/{envId}/subscriptions/{subscriptionId}/_accept:
    post:
      tags: [Subscriptions]
      operationId: acceptSubscription
      summary: Accept a Subscription
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: subscriptionId
          required: true
          schema: { type: string }
      responses:
        '200': { description: Subscription accepted }
  /environments/{envId}/subscriptions/{subscriptionId}/_reject:
    post:
      tags: [Subscriptions]
      operationId: rejectSubscription
      summary: Reject a Subscription
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: subscriptionId
          required: true
          schema: { type: string }
      responses:
        '200': { description: Subscription rejected }
  /environments/{envId}/api-products:
    get:
      tags: [API Products]
      operationId: getApiProducts
      summary: List API Products
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: API products page }
    post:
      tags: [API Products]
      operationId: createApiProduct
      summary: Create an API Product
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '201': { description: API product created }
  /environments/{envId}/api-products/_search:
    post:
      tags: [API Products]
      operationId: searchApiProducts
      summary: Search API Products
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Matching API products }
  /environments/{envId}/api-products/{apiProductId}:
    put:
      tags: [API Products]
      operationId: updateApiProduct
      summary: Update an API Product
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: apiProductId
          required: true
          schema: { type: string }
      responses:
        '200': { description: API product updated }
    delete:
      tags: [API Products]
      operationId: deleteApiProduct
      summary: Delete an API Product
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: apiProductId
          required: true
          schema: { type: string }
      responses:
        '204': { description: API product deleted }
  /environments/{envId}/analytics/definition/apis:
    get:
      tags: [Analytics]
      operationId: queryApiSpecs
      summary: Query API Analytics Specifications
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: API analytics specs }
  /environments/{envId}/analytics/measures:
    post:
      tags: [Analytics]
      operationId: queryMeasures
      summary: Query Analytics Measures
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Measures result }
  /environments/{envId}/analytics/facets:
    post:
      tags: [Analytics]
      operationId: queryFacets
      summary: Query Analytics Facets
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Facets result }
  /environments/{envId}/analytics/time-series:
    post:
      tags: [Analytics]
      operationId: queryTimeSeries
      summary: Query Analytics Time Series
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Time series result }
  /environments/{envId}/analytics/dashboards:
    get:
      tags: [Analytics]
      operationId: listDashboards
      summary: List Analytics Dashboards
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Dashboards page }
    post:
      tags: [Analytics]
      operationId: createDashboard
      summary: Create an Analytics Dashboard
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '201': { description: Dashboard created }
  /environments/{envId}/analytics/dashboards/{dashboardId}:
    get:
      tags: [Analytics]
      operationId: getDashboard
      summary: Get an Analytics Dashboard
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: dashboardId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The dashboard }
    put:
      tags: [Analytics]
      operationId: updateDashboard
      summary: Update an Analytics Dashboard
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: dashboardId
          required: true
          schema: { type: string }
      responses:
        '200': { description: Dashboard updated }
    delete:
      tags: [Analytics]
      operationId: deleteDashboard
      summary: Delete an Analytics Dashboard
      parameters:
        - $ref: '#/components/parameters/EnvId'
        - in: path
          name: dashboardId
          required: true
          schema: { type: string }
      responses:
        '204': { description: Dashboard deleted }
  /environments/{envId}/logs/search:
    post:
      tags: [Logs]
      operationId: searchLogs
      summary: Search Request Logs
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Logs page }
  /environments/{envId}/logs/error-keys:
    get:
      tags: [Logs]
      operationId: listErrorKeys
      summary: List Error Keys for Logs
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: Error keys }
  /environments:
    get:
      tags: [Installation]
      operationId: listEnvironments
      summary: List Environments
      responses:
        '200': { description: Environments }
  /environments/{envId}:
    get:
      tags: [Installation]
      operationId: getEnvironment
      summary: Get an Environment
      parameters:
        - $ref: '#/components/parameters/EnvId'
      responses:
        '200': { description: The environment }
  /organizations/{orgId}:
    get:
      tags: [Installation]
      operationId: getOrganization
      summary: Get an Organization
      parameters:
        - in: path
          name: orgId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The organization }
  /organizations/{orgId}/license:
    get:
      tags: [Installation]
      operationId: getOrganizationLicense
      summary: Get the Organization License
      parameters:
        - in: path
          name: orgId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The license }
  /plugins/endpoints:
    get:
      tags: [Plugins]
      operationId: listEndpointPlugins
      summary: List Endpoint Plugins
      responses:
        '200': { description: Endpoint plugins }
  /plugins/endpoints/{endpointId}:
    get:
      tags: [Plugins]
      operationId: getEndpointPlugin
      summary: Get an Endpoint Plugin
      parameters:
        - in: path
          name: endpointId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The endpoint plugin }
  /plugins/entrypoints:
    get:
      tags: [Plugins]
      operationId: listEntrypointPlugins
      summary: List Entrypoint Plugins
      responses:
        '200': { description: Entrypoint plugins }
  /plugins/policies:
    get:
      tags: [Plugins]
      operationId: listPolicyPlugins
      summary: List Policy Plugins
      responses:
        '200': { description: Policy plugins }
  /plugins/policies/{policyId}:
    get:
      tags: [Plugins]
      operationId: getPolicyPlugin
      summary: Get a Policy Plugin
      parameters:
        - in: path
          name: policyId
          required: true
          schema: { type: string }
      responses:
        '200': { description: The policy plugin }
  /plugins/resources:
    get:
      tags: [Plugins]
      operationId: listResourcePlugins
      summary: List Resource Plugins
      responses:
        '200': { description: Resource plugins }
  /users/{userId}/apis:
    get:
      tags: [Users]
      operationId: listUserApis
      summary: List APIs for a User
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: string }
      responses:
        '200': { description: User APIs }
  /users/{userId}/applications:
    get:
      tags: [Users]
      operationId: listUserApplications
      summary: List Applications for a User
      parameters:
        - in: path
          name: userId
          required: true
          schema: { type: string }
      responses:
        '200': { description: User applications }
  /ui/themes:
    get:
      tags: [UI]
      operationId: listUiThemes
      summary: List UI Themes
      responses:
        '200': { description: UI themes }
    post:
      tags: [UI]
      operationId: createUiTheme
      summary: Create a UI Theme
      responses:
        '201': { description: Theme created }
  /ui/themes/_current:
    get:
      tags: [UI]
      operationId: getCurrentUiTheme
      summary: Get the Current UI Theme
      responses:
        '200': { description: The current theme }
  /ui/customization:
    get:
      tags: [UI]
      operationId: getUiCustomization
      summary: Get UI Customization
      responses:
        '200': { description: UI customization }
components:
  parameters:
    EnvId:
      in: path
      name: envId
      required: true
      schema: { type: string }
      description: The environment identifier
    ApiId:
      in: path
      name: apiId
      required: true
      schema: { type: string }
      description: The API identifier
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    CookieAuth:
      type: apiKey
      in: cookie
      name: Auth-Graviteeio-APIM
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Api:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        apiVersion: { type: string }
        definitionVersion:
          type: string
          enum: [V1, V2, V4, FEDERATED]
        type:
          type: string
          enum: [PROXY, MESSAGE, NATIVE]
        description: { type: string }
        tags:
          type: array
          items: { type: string }
        labels:
          type: array
          items: { type: string }
        state:
          type: string
          enum: [STARTED, STOPPED]
        lifecycleState:
          type: string
          enum: [CREATED, PUBLISHED, UNPUBLISHED, ARCHIVED, DEPRECATED]
        visibility:
          type: string
          enum: [PUBLIC, PRIVATE]
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        deployedAt: { type: string, format: date-time }
    CreateApi:
      type: object
      required: [name, apiVersion, definitionVersion]
      properties:
        name: { type: string }
        description: { type: string }
        apiVersion: { type: string }
        definitionVersion:
          type: string
          enum: [V2, V4]
        type:
          type: string
          enum: [PROXY, MESSAGE, NATIVE]
    ImportSwaggerDescriptor:
      type: object
      required: [type, payload]
      properties:
        type:
          type: string
          enum: [INLINE, URL]
        payload: { type: string }
        format:
          type: string
          enum: [YAML, JSON]
        withDocumentation: { type: boolean }
        withPathMapping: { type: boolean }
    ApisPage:
      type: object
      properties:
        data:
          type: array
          items: { $ref: '#/components/schemas/Api' }
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        page: { type: integer }
        perPage: { type: integer }
        pageItemsCount: { type: integer }
        totalCount: { type: integer }
        pageCount: { type: integer }
    Plan:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: string }
        security:
          type: object
          properties:
            type:
              type: string
              enum: [KEY_LESS, API_KEY, OAUTH2, JWT, MTLS, SUBSCRIPTION, PUSH]
            configuration: { type: object }
        status:
          type: string
          enum: [STAGING, PUBLISHED, DEPRECATED, CLOSED]
        validation:
          type: string
          enum: [MANUAL, AUTO]
        order: { type: integer }
        characteristics:
          type: array
          items: { type: string }
    Application:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        description: { type: string }
        type:
          type: string
          enum: [SIMPLE, BROWSER, WEB, NATIVE, BACKEND_TO_BACKEND]
        status:
          type: string
          enum: [ACTIVE, ARCHIVED]
        settings:
          type: object
          properties:
            app:
              type: object
              properties:
                client_id: { type: string }
                type: { type: string }
            oauth:
              type: object
    Subscription:
      type: object
      properties:
        id: { type: string }
        api: { type: string }
        plan: { type: string }
        application: { type: string }
        status:
          type: string
          enum: [PENDING, ACCEPTED, REJECTED, CLOSED, PAUSED, RESUMED]
        createdAt: { type: string, format: date-time }
        startingAt: { type: string, format: date-time }
        endingAt: { type: string, format: date-time }