v5

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-07-0330110112.1 KB

APIs

Create or update APIs from APISpec

Create/update APIs from API Spec

put/organizations/{orgId}/environments/{envId}/apis

Path parameters

orgIdstring required

Example:dedd0e0f-b3e9-4d2f-89cd-b2a9de7cb145

organization ID

envIdstring required

Example:a44e0d1b-9fa9-4d64-8b76-3634623a2e27

environment ID

Query parameters

dryRunboolean

Example:true

For modifying requests, this parameter allow you to test the result of an endpoint without actually persisting the state of the underlying spec.

Request body

hridstring required

A unique human readable id identifying this resource

namestring required

API's name. Duplicate names can exists.

versionstring required

API's version. It's a simple string only used to help manage API versioning.

API's type.

descriptionstring

Basic API documentation to describe what this API does.

tagsstring[]

Sharding tags that restrict deployment to Gateways having those tags on. No tags means "always deploy".

responseTemplatesobject

Map of content-type dependent Response Templates for the API (Not applicable for Native API) to customize Gateway responses body on predefined errors.

Key of the map is the error code.

groupsstring[]

Name, HRID or UUIDs of existing groups (of users) associated with this API.

visibility'PUBLIC' | 'PRIVATE'

The visibility of the entity regarding the portal.

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

STARTED will make this API callable on tis context path, STOPPED will yield 404 error

labelsstring[]

Informative labels for this API.

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

The status of the API regarding the console.

categoriesstring[]

The list of category names (or UUID) associated with this API.

notifyMembersboolean

If true, new members added to the API spec will be notified when the API is synced with APIM.

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 request

{
  "hrid": "demo_api",
  "name": "My Api",
  "version": "1.0.0",
  "type": "MESSAGE",
  "description": "I can use many characters to describe this API.",
  "tags": [
    "europe"
  ],
  "listeners": [
    {
      "type": "HTTP",
      "entrypoints": [
        {
          "type": "http-get",
          "qos": "NONE"
        }
      ],
      "cors": {
        "allowOrigin": [
          "*",
          "http://api.acme\\.com",
          ".*\\.api\\.acme\\.com"
        ],
        "exposeHeaders": [
          "Content-Type"
        ]
      }
    }
  ],
  "endpointGroups": [
    {
      "name": "default-endpoint-group",
      "type": "http-proxy",
      "loadBalancer": {
        "type": "ROUND_ROBIN"
      },
      "endpoints": [
        {
          "name": "default-endpoint",
          "type": "http-proxy"
        }
      ]
    }
  ],
  "analytics": {
    "logging": {
      "condition": "{#request.headers['Content-Type'][0] == 'application/json'}",
      "messageCondition": "{ #message.headers['Content-Type'][0] == 'application/json'}"
    }
  },
  "resources": [
    {
      "type": "cache"
    }
  ],
  "plans": [
    {
      "hrid": "demo_api",
      "security": {
        "type": "KEY_LESS"
      },
      "status": "STAGING",
      "type": "API",
      "validation": "AUTO",
      "flows": [
        {
          "name": "My Flow",
          "selectors": [
            {
              "type": "HTTP",
              "path": "/my/path",
              "pathOperator": "EQUALS",
              "methods": [
                "GET"
              ]
            }
          ],
          "tags": [
            "tag1",
            "tag2"
          ]
        }
      ],
      "mode": "STANDARD",
      "bootstrapPort": 9092,
      "brokerRangeStart": 9100,
      "brokerRangeEnd": 9102
    }
  ],
  "flowExecution": {
    "mode": "BEST_MATCH"
  },
  "flows": [
    {
      "name": "My Flow",
      "selectors": [
        {
          "type": "HTTP",
          "path": "/my/path",
          "pathOperator": "EQUALS",
          "methods": [
            "GET"
          ]
        }
      ],
      "tags": [
        "tag1",
        "tag2"
      ]
    }
  ],
  "groups": [
    "developers"
  ],
  "visibility": "PUBLIC",
  "state": "STARTED",
  "primaryOwner": {
    "id": "00f8c9e7-78fc-4907-b8c9-e778fc790750",
    "email": "john.doe@example.com",
    "displayName": "John Doe",
    "type": "USER"
  },
  "labels": [
    "example"
  ],
  "metadata": [
    {
      "format": "STRING"
    }
  ],
  "lifecycleState": "CREATED",
  "categories": [
    "Example APIs"
  ],
  "members": [
    {
      "source": "gravitee",
      "sourceId": "john.doe@example.com",
      "role": "REVIEWER"
    }
  ],
  "pages": [
    {
      "hrid": "demo_api",
      "crossId": "00f8c9e7-78fc-4907-b8c9-e778fc790750",
      "name": "My Page",
      "type": "MARKDOWN",
      "content": "My Page content",
      "published": true,
      "visibility": "PUBLIC",
      "source": {
        "type": "http-fetcher"
      },
      "configuration": {
        "viewer": "Redoc"
      },
      "homepage": true,
      "parentHrid": "guides"
    }
  ],
  "portalNavigation": [
    {
      "path": "/projects/alpha",
      "displayName": "Alpha",
      "order": 1
    }
  ]
}

Response

State of the successfully created/updated API