Subscriptions¶

Create a subscription¶

POST /subscriptions

Code samples

curl -X POST https://localhost:9543/api/v0.9/subscriptions \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Creates a subscription for an API. The API must exist in the Developer Portal and have subscription plans enabled. The subscription is owned by the authenticated user.

Payload

{
  "artifactId": "weather-api-v1",
  "subscriptionPlanId": "Gold"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	SubscriptionCreateRequest	true	Subscription creation payload. `artifactId` is the Developer Portal API ID.

Example responses

201 Response

{
  "subscriptionId": "sub-12345",
  "artifactId": "weather-api-v1",
  "subscriptionToken": "a3f1e8b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1",
  "subscriptionPlanName": "Gold",
  "status": "ACTIVE",
  "createdBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "Conflict"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
201	Created	Subscription DTO.	SubscriptionResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
409	Conflict	The request conflicts with an existing resource.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Response Headers¶

Status	Header	Type	Format	Description
201	Location	string	uri	URL of the created subscription.

List subscriptions¶

GET /subscriptions

Code samples

curl -X GET https://localhost:9543/api/v0.9/subscriptions \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Lists subscriptions owned by the authenticated user. When artifactId is provided, results are additionally filtered by the Developer Portal API ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
artifactId	query	string	false	Optional Developer Portal API ID used to filter results.
limit	query	integer	false	Maximum number of records to return.
offset	query	integer	false	Number of records to skip before returning results.

Example responses

200 Response

{
  "list": [
    {
      "subscriptionId": "sub-12345",
      "artifactId": "weather-api-v1",
      "subscriptionToken": "a3f1e8b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1",
      "subscriptionPlanName": "Gold",
      "status": "ACTIVE",
      "createdBy": "[email protected]",
      "createdAt": "2026-05-07T08:30:00Z",
      "updatedAt": "2026-05-07T08:30:00Z"
    }
  ],
  "count": 1,
  "pagination": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

404 Response

{
  "status": "error",
  "code": "RESOURCE_NOT_FOUND",
  "message": "API not found"
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	List of subscription DTOs.	Inline
404	Not Found	Returned when `artifactId` is provided but does not match an existing API.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» list	[SubscriptionResponse]	false	none	[Subscription payload.]
»» subscriptionId	string	false	none	none
»» artifactId	string	false	none	Developer Portal API ID.
»» subscriptionToken	string¦null	false	none	Plaintext subscription token, decrypted on every read (not just on create). Null if decryption fails (e.g. the encryption key changed since the token was stored).
»» subscriptionPlanName	string	false	none	none
»» status	string	false	none	none
»» createdBy	string	false	none	Identity of the user who created the subscription, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses and list items.
»» updatedBy	string	false	none	Identity of the user who last updated the subscription, or `deleted_user` if that user's IDP reference no longer exists. Present on single-resource GET responses only, omitted on list items.
»» createdAt	string(date-time)	false	none	none
»» updatedAt	string(date-time)	false	none	none
» count	integer	false	none	Number of items returned in this page.
» pagination	Pagination	false	none	Standard pagination metadata returned with collection responses.
»» total	integer	true	none	Total number of records matching the query.
»» limit	integer	true	none	Maximum number of records returned in this response.
»» offset	integer	true	none	Number of records skipped before this page.

Enumerated Values

Property	Value
status	ACTIVE
status	INACTIVE

Get a subscription¶

GET /subscriptions/{subId}

Code samples

curl -X GET https://localhost:9543/api/v0.9/subscriptions/{subId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Retrieves a single subscription by subscription ID.

Authentication¶

Parameters

Name	In	Type	Required	Description
subId	path	string	true	none

Example responses

200 Response

{
  "subscriptionId": "sub-12345",
  "artifactId": "weather-api-v1",
  "subscriptionToken": "a3f1e8b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1",
  "subscriptionPlanName": "Gold",
  "status": "ACTIVE",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z",
  "updatedAt": "2026-05-07T08:30:00Z"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription DTO.	SubscriptionResponse
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Update a subscription¶

PUT /subscriptions/{subId}

Code samples

curl -X PUT https://localhost:9543/api/v0.9/subscriptions/{subId} \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Updates the subscription status. Accepts only ACTIVE or INACTIVE.

Payload

{
  "status": "ACTIVE"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	SubscriptionUpdateRequest	true	Subscription status update payload.
subId	path	string	true	none

Example responses

200 Response

{
  "subscriptionId": "sub-12345",
  "artifactId": "weather-api-v1",
  "subscriptionToken": "a3f1e8b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1",
  "subscriptionPlanName": "Gold",
  "status": "ACTIVE",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z",
  "updatedAt": "2026-05-07T08:30:00Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription DTO.	SubscriptionResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Delete a subscription¶

DELETE /subscriptions/{subId}

Code samples

curl -X DELETE https://localhost:9543/api/v0.9/subscriptions/{subId} \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Deletes the subscription and returns a success message.

Authentication¶

Parameters

Name	In	Type	Required	Description
subId	path	string	true	none

Example responses

200 Response

{
  "message": "string"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	JSON message response.	MessageResponse
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Change subscription plan¶

POST /subscriptions/{subId}/change-plan

Code samples

curl -X POST https://localhost:9543/api/v0.9/subscriptions/{subId}/change-plan \
  -u {username}:{password} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d @payload.json

Changes the subscription plan in-place. The subscription UUID and token remain unchanged; only the plan is updated. A subscription.plan_changed webhook event is published to the organization's configured webhook subscribers.

Payload

{
  "artifactId": "weather-api-v1",
  "planId": "Gold"
}

Authentication¶

Parameters

Name	In	Type	Required	Description
body	body	SubscriptionChangePlanRequest	true	Subscription plan change payload. `planId` is the Developer Portal subscription plan ID.
subId	path	string	true	none

Example responses

200 Response

{
  "subscriptionId": "sub-12345",
  "artifactId": "weather-api-v1",
  "subscriptionToken": "a3f1e8b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1",
  "subscriptionPlanName": "Gold",
  "status": "ACTIVE",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z",
  "updatedAt": "2026-05-07T08:30:00Z"
}

Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its errors array); some legacy handlers return a message-only object.

{
  "status": "error",
  "code": "MISSING_REQUIRED_PARAMETER",
  "message": "Missing required parameter."
}

{
  "message": "Missing or invalid fields in the request payload"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription DTO.	SubscriptionResponse
400	Bad Request	Bad request. Validation and other bad-request errors are returned as a standard error object (field-level details, when present, are carried in its `errors` array); some legacy handlers return a message-only object.	Inline
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse

Response Schema

Enumerated Values

Property	Value
status	error

Regenerate subscription token¶

POST /subscriptions/{subId}/regenerate-token

Code samples

curl -X POST https://localhost:9543/api/v0.9/subscriptions/{subId}/regenerate-token \
  -u {username}:{password} \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}'

Regenerates the subscription token, immediately invalidating the old one. A subscription.token_regenerated webhook event is published to the organization's configured webhook subscribers so they can update the token at the gateway. The new plaintext token is returned in the response.

Authentication¶

Parameters

Name	In	Type	Required	Description
subId	path	string	true	none

Example responses

200 Response

{
  "subscriptionId": "sub-12345",
  "artifactId": "weather-api-v1",
  "subscriptionToken": "a3f1e8b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1b3c5d7e9f10b2c4d6e8f0a1",
  "subscriptionPlanName": "Gold",
  "status": "ACTIVE",
  "createdBy": "[email protected]",
  "updatedBy": "[email protected]",
  "createdAt": "2026-05-07T08:30:00Z",
  "updatedAt": "2026-05-07T08:30:00Z"
}

404 Response

{
  "status": "error",
  "code": "ORG_NOT_FOUND",
  "message": "Organization not found."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred."
}

Responses

Status	Meaning	Description	Schema
200	OK	Subscription DTO.	SubscriptionResponse
404	Not Found	Resource not found.	ErrorResponse
500	Internal Server Error	Internal server error.	ErrorResponse