WebSub API Management

Create a new WebSubAPI

POST /websub-apis

Code samples

curl -X POST http://localhost:9090/api/management/v0.9/websub-apis \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Add a new WebSubAPI to the Gateway.

Payload

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebSubApi",
  "metadata": {
    "name": "github-events-v1.0"
  },
  "spec": {
    "displayName": "GitHub Events",
    "version": "v1.0",
    "context": "/github-events/$version",
    "channels": [
      {
        "name": "issues",
        "method": "SUB"
      },
      {
        "name": "pull_requests",
        "method": "SUB"
      }
    ]
  }
}

Authentication

Parameters

Name	In	Type	Required	Description
body	body	WebSubAPIRequest	true	none

Example responses

201 Response

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebSubApi",
  "metadata": {
    "name": "github-events-v1.0"
  },
  "spec": {
    "displayName": "GitHub Events",
    "version": "v1.0",
    "context": "/github-events/$version",
    "channels": [
      {
        "name": "issues",
        "method": "SUB"
      },
      {
        "name": "pull_requests",
        "method": "SUB"
      }
    ]
  },
  "status": {
    "id": "github-events-v1.0",
    "state": "deployed",
    "createdAt": "2026-04-24T07:21:13Z",
    "updatedAt": "2026-04-24T07:21:13Z",
    "deployedAt": "2026-04-24T07:21:13Z"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	WebSubAPI created successfully	WebSubAPI
400	Bad Request	Invalid configuration (validation failed)	ErrorResponse
409	Conflict	Conflict - WebSub API with same name and version already exists	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

List all WebSubAPIs

GET /websub-apis

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/websub-apis \
  -u {username}:{password} \
  -H 'Accept: application/json'

List WebSubAPIs registered in the Gateway, optionally filtered by name, version, context, or status.

Authentication

Parameters

Name	In	Type	Required	Description
displayName	query	string	false	Filter by WebSub API display name
version	query	string	false	Filter by WebSub API version
context	query	string	false	Filter by WebSub API context/path
status	query	string	false	Filter by deployment status

Enumerated Values

Parameter	Value
status	deployed
status	undeployed

Example responses

200 Response

{
  "status": "success",
  "count": 5,
  "apis": [
    {
      "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
      "kind": "WebSubApi",
      "metadata": {
        "name": "github-events-v1.0"
      },
      "spec": {
        "displayName": "GitHub Events",
        "version": "v1.0",
        "context": "/github-events/$version",
        "channels": [
          {
            "name": "issues",
            "method": "SUB"
          },
          {
            "name": "pull_requests",
            "method": "SUB"
          }
        ]
      },
      "status": {
        "id": "github-events-v1.0",
        "state": "deployed",
        "createdAt": "2026-04-24T07:21:13Z",
        "updatedAt": "2026-04-24T07:21:13Z",
        "deployedAt": "2026-04-24T07:21:13Z"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	List of WebSubAPIs	Inline
500	Internal Server Error	Internal server error	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» status	string	false	none	none
» count	integer	false	none	none
» apis	[allOf]	false	none	none

allOf

Name	Type	Required	Restrictions	Description
»» anonymous	WebSubAPIRequest	false	none	none
»»» apiVersion	string	true	none	API specification version
»»» kind	string	true	none	API type
»»» metadata	Metadata	true	none	none
»»»» name	string	true	none	Unique handle for the resource
»»»» labels	object	false	none	Labels are key-value pairs for organizing and selecting APIs. Keys must not contain spaces.
»»»»» additionalProperties	string	false	none	none
»»»» annotations	object	false	none	Annotations are arbitrary non-identifying metadata. Use domain-prefixed keys.
»»»»» additionalProperties	string	false	none	none
»»» spec	WebhookAPIData	true	none	none
»»»» displayName	string	true	none	Human-readable API name (must be URL-friendly - only letters, numbers, spaces, hyphens, underscores, and dots allowed)
»»»» version	string	true	none	Semantic version of the API
»»»» context	string	true	none	Base path for all API routes (must start with /, no trailing slash)
»»»» vhosts	object	false	none	Custom virtual hosts/domains for the API
»»»»» main	string	true	none	Custom virtual host/domain for production traffic
»»»»» sandbox	string	false	none	Custom virtual host/domain for sandbox traffic
»»»» allChannels	WebSubAllChannelPolicies	false	none	Policies applied to all channels, organized by event type.
»»»»» on_subscription	WebSubEventPolicies	false	none	Policies for a single event type.
»»»»»» policies	[Policy]	false	none	List of policies applied for this event type.
»»»»»»» name	string	true	none	Name of the policy
»»»»»»» version	string	true	none	Version of the policy. Only major-only version is allowed (e.g., v0, v1). Full semantic version (e.g., v1.0.0) is not accepted and will be rejected. The Gateway Controller resolves the major version to the single matching full version installed in the gateway image.
»»»»»»» executionCondition	string	false	none	Expression controlling conditional execution of the policy
»»»»»»» params	object	false	none	Arbitrary parameters for the policy (free-form key/value structure)
»»»»» on_unsubscription	WebSubEventPolicies	false	none	Policies for a single event type.
»»»»» on_message_received	WebSubEventPolicies	false	none	Policies for a single event type.
»»»»» on_message_delivery	WebSubEventPolicies	false	none	Policies for a single event type.
»»»» channels	object	false	none	Per-channel configuration keyed by channel name. Each key is a channel name and defines policies applied only to that channel.
»»»»» additionalProperties	WebSubChannel	false	none	A single channel definition with optional per-channel policy overrides.
»»»»»» on_subscription	WebSubEventPolicies	false	none	Policies for a single event type.
»»»»»» on_unsubscription	WebSubEventPolicies	false	none	Policies for a single event type.
»»»»»» on_message_received	WebSubEventPolicies	false	none	Policies for a single event type.
»»»»»» on_message_delivery	WebSubEventPolicies	false	none	Policies for a single event type.
»»»» deploymentState	string	false	none	Desired deployment state - 'deployed' (default) or 'undeployed'. When set to 'undeployed', the API is removed from router traffic but configuration, API keys, and policies are preserved for potential redeployment.

and

Name	Type	Required	Restrictions	Description
»» anonymous	object	false	none	none
»»» status	ResourceStatus	false	read-only	Server-managed lifecycle fields. Populated on responses.
»»»» id	string	false	none	Unique identifier assigned by the server (equal to metadata.name)
»»»» state	string	false	none	Desired deployment state reported by the server
»»»» createdAt	string(date-time)	false	none	Timestamp when the resource was first created (UTC)
»»»» updatedAt	string(date-time)	false	none	Timestamp when the resource was last updated (UTC)
»»»» deployedAt	string(date-time)	false	none	Timestamp when the resource was last deployed (omitted when undeployed)

Enumerated Values

Property	Value
apiVersion	gateway.api-platform.wso2.com/v1alpha1
kind	WebSubApi
deploymentState	deployed
deploymentState	undeployed
state	deployed
state	undeployed

Create a new API key for a WebSub API

POST /websub-apis/{id}/api-keys

Code samples

curl -X POST http://localhost:9090/api/management/v0.9/websub-apis/{id}/api-keys \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Generate a new API key for a WebSub API in the Gateway. The key is a 32-byte random value encoded in hexadecimal, prefixed with apip_. Use the API Key policy on the API to validate incoming requests with this key.

Payload

{
  "name": "my-production-key"
}

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API to generate the key for
body	body	APIKeyCreationRequest	true	none

Example responses

201 Response

{
  "status": "success",
  "message": "API key generated successfully",
  "remainingApiKeyQuota": 9,
  "apiKey": {
    "name": "my-production-key",
    "displayName": "My Production Key",
    "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "apiId": "reading-list-api-v1.0",
    "status": "active",
    "createdAt": "2026-04-01T10:30:00Z",
    "createdBy": "admin",
    "expiresAt": null,
    "source": "local"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	API key created successfully	APIKeyCreationResponse
400	Bad Request	Invalid configuration (validation failed)	ErrorResponse
404	Not Found	WebSub API not found	ErrorResponse
409	Conflict	Conflict (duplicate key or conflicting update)	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Get the list of API keys for a WebSub API

GET /websub-apis/{id}/api-keys

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/websub-apis/{id}/api-keys \
  -u {username}:{password} \
  -H 'Accept: application/json'

List all API keys for a WebSub API in the Gateway.

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API to retrieve the keys for

Example responses

200 Response

{
  "apiKeys": [
    {
      "name": "my-production-key",
      "displayName": "My Production Key",
      "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "apiId": "reading-list-api-v1.0",
      "status": "active",
      "createdAt": "2026-04-01T10:30:00Z",
      "createdBy": "admin",
      "expiresAt": null,
      "source": "local"
    }
  ],
  "totalCount": 3,
  "status": "success"
}

Responses

Status	Meaning	Description	Schema
200	OK	List of API keys	APIKeyListResponse
404	Not Found	WebSub API not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Regenerate API key for a WebSub API

POST /websub-apis/{id}/api-keys/{apiKeyName}/regenerate

Code samples

curl -X POST http://localhost:9090/api/management/v0.9/websub-apis/{id}/api-keys/{apiKeyName}/regenerate \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Regenerate an existing API key for a WebSub API in the Gateway. The previous key is revoked and replaced with a new 32-byte random value encoded in hexadecimal, prefixed with apip_.

Payload

{}

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API
apiKeyName	path	string	true	Name of the API key to regenerate
body	body	APIKeyRegenerationRequest	true	none

Example responses

200 Response

{
  "status": "success",
  "message": "API key generated successfully",
  "remainingApiKeyQuota": 9,
  "apiKey": {
    "name": "my-production-key",
    "displayName": "My Production Key",
    "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "apiId": "reading-list-api-v1.0",
    "status": "active",
    "createdAt": "2026-04-01T10:30:00Z",
    "createdBy": "admin",
    "expiresAt": null,
    "source": "local"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	API key rotated successfully	APIKeyCreationResponse
400	Bad Request	Invalid configuration (validation failed)	ErrorResponse
404	Not Found	WebSub API or API key not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Update an API key for a WebSub API

PUT /websub-apis/{id}/api-keys/{apiKeyName}

Code samples

curl -X PUT http://localhost:9090/api/management/v0.9/websub-apis/{id}/api-keys/{apiKeyName} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Update an API key with a custom value instead of auto-generating one.

Payload

{
  "name": "my-production-key"
}

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API
apiKeyName	path	string	true	Name of the API key to update
body	body	APIKeyUpdateRequest	true	none

Example responses

200 Response

{
  "status": "success",
  "message": "API key generated successfully",
  "remainingApiKeyQuota": 9,
  "apiKey": {
    "name": "my-production-key",
    "displayName": "My Production Key",
    "apiKey": "apip_1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "apiId": "reading-list-api-v1.0",
    "status": "active",
    "createdAt": "2026-04-01T10:30:00Z",
    "createdBy": "admin",
    "expiresAt": null,
    "source": "local"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	API key updated successfully	APIKeyCreationResponse
400	Bad Request	Invalid request (validation failed)	ErrorResponse
404	Not Found	WebSub API or API key not found	ErrorResponse
409	Conflict	Conflict (duplicate key or conflicting update)	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Revoke an API key for a WebSub API

DELETE /websub-apis/{id}/api-keys/{apiKeyName}

Code samples

curl -X DELETE http://localhost:9090/api/management/v0.9/websub-apis/{id}/api-keys/{apiKeyName} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Revoke an API key. Once revoked, it can no longer be used to authenticate requests.

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API
apiKeyName	path	string	true	Name of the API key to revoke

Example responses

200 Response

{
  "status": "success",
  "message": "API key revoked successfully"
}

Responses

Status	Meaning	Description	Schema
200	OK	API key revoked successfully	APIKeyRevocationResponse
400	Bad Request	Invalid configuration (validation failed)	ErrorResponse
404	Not Found	WebSub API or API key not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Get WebSubAPI by id

GET /websub-apis/{id}

Code samples

curl -X GET http://localhost:9090/api/management/v0.9/websub-apis/{id} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Get a WebSubAPI by its ID.

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier for the WebSub API.

Detailed descriptions

id: Unique public identifier for the WebSub API.

Example responses

200 Response

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebSubApi",
  "metadata": {
    "name": "github-events-v1.0"
  },
  "spec": {
    "displayName": "GitHub Events",
    "version": "v1.0",
    "context": "/github-events/$version",
    "channels": [
      {
        "name": "issues",
        "method": "SUB"
      },
      {
        "name": "pull_requests",
        "method": "SUB"
      }
    ]
  },
  "status": {
    "id": "github-events-v1.0",
    "state": "deployed",
    "createdAt": "2026-04-24T07:21:13Z",
    "updatedAt": "2026-04-24T07:21:13Z",
    "deployedAt": "2026-04-24T07:21:13Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	WebSubAPI details	WebSubAPI
404	Not Found	WebSubAPI not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Update an existing WebSubAPI

PUT /websub-apis/{id}

Code samples

curl -X PUT http://localhost:9090/api/management/v0.9/websub-apis/{id} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Update an existing WebSubAPI in the Gateway.

Payload

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebSubApi",
  "metadata": {
    "name": "github-events-v1.0"
  },
  "spec": {
    "displayName": "GitHub Events",
    "version": "v1.0",
    "context": "/github-events/$version",
    "channels": [
      {
        "name": "issues",
        "method": "SUB"
      },
      {
        "name": "pull_requests",
        "method": "SUB"
      }
    ]
  }
}

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API to update.
body	body	WebSubAPIRequest	true	none

Detailed descriptions

id: Unique public identifier of the WebSub API to update.

Example responses

200 Response

{
  "apiVersion": "gateway.api-platform.wso2.com/v1alpha1",
  "kind": "WebSubApi",
  "metadata": {
    "name": "github-events-v1.0"
  },
  "spec": {
    "displayName": "GitHub Events",
    "version": "v1.0",
    "context": "/github-events/$version",
    "channels": [
      {
        "name": "issues",
        "method": "SUB"
      },
      {
        "name": "pull_requests",
        "method": "SUB"
      }
    ]
  },
  "status": {
    "id": "github-events-v1.0",
    "state": "deployed",
    "createdAt": "2026-04-24T07:21:13Z",
    "updatedAt": "2026-04-24T07:21:13Z",
    "deployedAt": "2026-04-24T07:21:13Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	WebSubAPI updated successfully	WebSubAPI
400	Bad Request	Invalid configuration (validation failed)	ErrorResponse
404	Not Found	WebSubAPI not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Delete a WebSubAPI

DELETE /websub-apis/{id}

Code samples

curl -X DELETE http://localhost:9090/api/management/v0.9/websub-apis/{id} \
  -u {username}:{password} \
  -H 'Accept: application/json'

Delete a WebSubAPI from the Gateway.

Authentication

Parameters

Name	In	Type	Required	Description
id	path	string	true	Unique public identifier of the WebSub API to delete.

Detailed descriptions

id: Unique public identifier of the WebSub API to delete.

Example responses

200 Response

{
  "status": "success",
  "message": "WebSubAPI deleted successfully",
  "id": "weather-websub-api"
}

Responses

Status	Meaning	Description	Schema
200	OK	WebSubAPI deleted successfully	Inline
404	Not Found	WebSubAPI not found	ErrorResponse
500	Internal Server Error	Internal server error	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» status	string	false	none	none
» message	string	false	none	none
» id	string	false	none	none