Sign in

v2

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

Create an API

Create an API

⚠️ Support only v4 API for the moment. ⚠️<br> Create a new API.

For V4 PROXY APIs, provide listeners with HTTP paths and an http-proxy entrypoint, plus endpointGroups with an http-proxy endpoint. Example request body: {"name":"My API","apiVersion":"1.0","definitionVersion":"V4","type":"PROXY","listeners":[{"type":"HTTP","paths":[{"path":"/my-api"}],"entrypoints":[{"type":"http-proxy"}]}],"endpointGroups":[{"name":"default","type":"http-proxy","endpoints":[{"name":"backend","type":"http-proxy","configuration":{"target":"https://backend.example.com"}}]}]}

post/environments/{envId}/apis

Request body

namestring required

API's name. Duplicate names can exists.

apiVersionstring required

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

descriptionstring

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

visibility'PUBLIC' | 'PRIVATE'

The visibility of the resource regarding the portal.

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

API's gravitee definition version.

groupsstring[]

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

type'A2A_PROXY' | 'AUTHZ' | 'EDGE' | 'LLM_PROXY' | 'MCP_PROXY' | 'MESSAGE' | 'NATIVE' | 'PROXY' required

API's type.

tagsstring[]

The list of sharding tags associated with this API.

allowedInApiProductsboolean

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

Example request

{
  "name": "My Api",
  "apiVersion": "v1.0",
  "description": "I can use many characters to describe this API.",
  "visibility": "PUBLIC",
  "definitionVersion": "V4",
  "groups": [
    "6c530064-0b2c-4004-9300-640b2ce0047b",
    "12559b64-0b2c-4004-9300-640b2ce0047b"
  ],
  "type": "MESSAGE",
  "tags": [
    "public",
    "private"
  ],
  "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"
      ]
    }
  ],
  "allowedInApiProducts": true
}

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
type'A2A_PROXY' | 'AUTHZ' | 'EDGE' | 'LLM_PROXY' | 'MCP_PROXY' | 'MESSAGE' | 'NATIVE' | 'PROXY'

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