v2

latestOpenAPI 3.0.3Apache 2.0raw.githubusercontent.com2026-07-21130282381.6 KB

APIs

Update API from a definition fetched from a remote URL

⚠️ Support only v4 API for the moment. ⚠️<br> Update an existing API by fetching a Gravitee API definition from a remote URL.<br> The URL must be permitted by the configured import whitelist.

put/environments/{envId}/apis/{apiId}/_import/definition-url

Response

API successfully updated

idstring

API's uuid.

namestring

API's name. Duplicate names can exists.

descriptionstring

API's description. A short description of your API.

crossIdstring

API's crossId. Identifies API across environments.

apiVersionstring

API's version. It's a simple string only used in the portal.

definitionVersion'V2' | 'V4' | 'FEDERATED' | 'FEDERATED_AGENT' required

API's gravitee definition version.

deployedAtstring date-time

The last date (as timestamp) when the API was deployed.

createdAtstring date-time

The date (as timestamp) when the API was created.

updatedAtstring date-time

The last date (as timestamp) when the API was updated.

disableMembershipNotificationsboolean

Disable membership notifications.

metadataobject

API metadata as key-value pairs, populated only when expands=metadata is requested.

groupsstring[]

List of group IDs associated with this API. Used to manage team access.

state'CLOSED' | 'INITIALIZED' | 'STARTED' | 'STOPPED' | 'STOPPING'

The state of the API regarding the gateway(s).

deploymentState'NEED_REDEPLOY' | 'DEPLOYED'

The deployment state of the API regarding the gateway(s).

visibility'PUBLIC' | 'PRIVATE'

The visibility of the resource regarding the portal.

labelsstring[]

The free list of labels associated with this API.

lifecycleState'ARCHIVED' | 'CREATED' | 'DEPRECATED' | 'PUBLISHED' | 'UNPUBLISHED'

The status of the API regarding the console.

tagsstring[]

The list of sharding tags associated with this API.

categoriesstring[]

The list of category keys associated with this API.

workflowState'DRAFT' | 'IN_REVIEW' | 'REQUEST_FOR_CHANGES' | 'REVIEW_OK'

The status of the API regarding the review feature.

responseTemplatesobject

API's type.

allowedInApiProductsboolean

Indicates whether this API is allowed to be used in API Products. Only applicable for V4 HTTP Proxy APIs.

allowMultiJwtOauth2Subscriptionsboolean

Allow an application to subscribe to more than one JWT/OAuth2 plan (V4 only).

Example response

{
  "id": "00f8c9e7-78fc-4907-b8c9-e778fc790750",
  "name": "My Api",
  "description": "I can use many characters to describe this API.",
  "crossId": "df83b2a4-cc3e-3f80-9f0d-c138c106c076",
  "apiVersion": "v1.0",
  "definitionVersion": "V4",
  "groups": [
    "6c530064-0b2c-4004-9300-640b2ce0047b",
    "12559b64-0b2c-4004-9300-640b2ce0047b"
  ],
  "state": "STARTED",
  "deploymentState": "DEPLOYED",
  "visibility": "PUBLIC",
  "labels": [
    "json",
    "read_only",
    "awesome"
  ],
  "lifecycleState": "CREATED",
  "tags": [
    "public",
    "private"
  ],
  "primaryOwner": {
    "id": "00f8c9e7-78fc-4907-b8c9-e778fc790750",
    "displayName": "John Doe"
  },
  "categories": [
    "health",
    "media"
  ],
  "originContext": {
    "origin": "MANAGEMENT"
  },
  "definitionContext": {
    "origin": "MANAGEMENT",
    "mode": "FULLY_MANAGED",
    "syncFrom": "MANAGEMENT"
  },
  "workflowState": "DRAFT",
  "_links": {
    "pictureUrl": "https://gravitee.example.com/management/v2/environments/00f8c9e7-78fc-4907-b8c9-e778fc790750/apis/6c530064-0b2c-4004-9300-640b2ce0047b/picture",
    "backgroundUrl": "https://gravitee.example.com/management/v2/environments/00f8c9e7-78fc-4907-b8c9-e778fc790750/apis/6c530064-0b2c-4004-9300-640b2ce0047b/background"
  },
  "type": "MESSAGE",
  "listeners": [
    {
      "type": "HTTP",
      "entrypoints": [
        {
          "type": "http-get",
          "qos": "NONE"
        }
      ]
    }
  ],
  "endpointGroups": [
    {
      "name": "default-endpoint-group",
      "type": "default",
      "loadBalancer": {
        "type": "ROUND_ROBIN"
      },
      "endpoints": [
        {
          "name": "default-endpoint",
          "type": "mock"
        }
      ]
    }
  ],
  "analytics": {
    "tracing": {
      "redaction": {
        "defaultReplacement": "[REDACTED]",
        "rules": [
          {
            "attributeNamePattern": "http.request.header.authorization",
            "maskingStrategy": {
              "type": "FULL",
              "replacement": "[REDACTED]"
            },
            "valuePattern": "^Bearer "
          }
        ]
      }
    }
  },
  "flowExecution": {
    "mode": "BEST_MATCH"
  },
  "flows": [
    {
      "id": "4e6abbd2-c0c6-462d-be9e-6371209af34b",
      "name": "My Flow",
      "selectors": [
        {
          "type": "HTTP",
          "path": "/my/path",
          "pathOperator": "EQUALS",
          "methods": [
            "GET"
          ]
        }
      ],
      "tags": [
        "tag1",
        "tag2"
      ]
    }
  ]
}