v2

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

APIs

Import API definition

⚠️ Support only v4 API for the moment. ⚠️<br> Create an API by importing from an Open API descriptor. <br> This definition can be retrieved from GET /environments/{envId}/apis/{apiId}/_export/definition

post/environments/{envId}/apis/_import/swagger

Request body

payloadstring

The Swagger/OpenAPI content.

withDocumentationboolean

Create documentation based on Swagger/OpenAPI specification.

withOASValidationPolicyboolean

Add an OpenAPI Specification validation policy based on OpenAPI specification.

withPoliciesstring[]

Policy visitor IDs to apply during OpenAPI import.

withPolicyPathsboolean

Create a flow for each path declared in the OpenAPI specification.

Response

API successfully created

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"
      ]
    }
  ]
}