OutSystems ODC Subscription API
REST endpoints for retrieving subscription and entitlement data and usage metrics for an OutSystems Developer Cloud organization.
OpenAPI Specification
{
"openapi": "3.0.3",
"info": {
"title": "Subscription API",
"description": "REST endpoints for retrieving information about subscription and entitlement data and usage.\n",
"version": "v1"
},
"servers": [
{
"url": "https://ODC_PORTAL_DOMAIN/api/subscription/v1",
"description": "Replace ODC_PORTAL_DOMAIN with the domain of your organization."
},
{
"url": "https://{odc-portal-domain}/api/subscription/v1",
"description": "Replace {odc-portal-domain} with the domain of your organization.",
"variables": {
"{odc-portal-domain}": {
"default": "{odc-portal-domain}",
"description": "The domain of your organization"
}
}
}
],
"paths": {
"/environments/{environmentKey}/entitlements/usage/by-asset": {
"get": {
"tags": [],
"summary": "Retrieves usage data per asset (application, library) for entitlements in a specific environment.",
"description": "Paginated; supports filtering and sort by metric.\n\nTo fetch the usage, API Client needs the **Stage > View stage** and **Subscriptions > View subscription** permissions in the target stage.",
"operationId": "Subscription_GetAssetUsage",
"parameters": [
{
"name": "environmentKey",
"in": "path",
"description": "Environment key",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "entitlementIds",
"in": "query",
"description": "Optional comma-separated entitlement IDs. Valid values: applicationObjects, maxComputeReplicas, maxCustomCodeTotalDuration, agentExecutions",
"schema": {
"type": "string"
}
},
{
"name": "assetKeys",
"in": "query",
"description": "Optional comma-separated asset keys (GUIDs) to filter results",
"schema": {
"type": "string"
}
},
{
"name": "assetName",
"in": "query",
"description": "Optional partial or full asset name for case-insensitive search",
"schema": {
"type": "string"
}
},
{
"name": "detailKey",
"in": "query",
"description": "Optional filter by detail key",
"schema": {
"type": "string"
}
},
{
"name": "detailName",
"in": "query",
"description": "Optional filter by detail name (case-insensitive partial match)",
"schema": {
"type": "string"
}
},
{
"name": "sortBy",
"in": "query",
"description": "Comma-separated metrics to sort by. Prefix with '+' for ascending (default) or '-' for descending. Example: \"applicationObjects,-maxComputeReplicas\"",
"schema": {
"type": "string"
}
},
{
"name": "since",
"in": "query",
"description": "Start date for usage data (ISO 8601 format)",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "End date for usage data (ISO 8601 format)",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "Maximum number of asset rows to return. Default: 100.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "offset",
"in": "query",
"description": "Number of asset rows to skip for pagination. Default: 0.",
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "aggregations",
"in": "query",
"description": "Optional comma-separated aggregation functions. Valid values: Total, Max, P95, P90",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnifiedEntitlementByAssetBlockPagedListResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"x-os-permissions": "To fetch the usage, API Client needs the **Stage > View stage** and **Subscriptions > View subscription** permissions in the target stage."
}
},
"/environments/{environmentKey}/entitlements": {
"get": {
"tags": [],
"summary": "Retrieves information on the entitlements for a specific environment.",
"description": "Entitlements and add-ons are shown with sufficient permissions.\n\nTo fetch the entitlements, API Client needs the **Stage > View stage** permission in the target stage.\nTo additionally fetch the add-ons, API Client also needs the **Subscriptions > View subscription** permission.",
"operationId": "Subscription_GetEnvironmentEntitlements",
"parameters": [
{
"name": "environmentKey",
"in": "path",
"description": "Environment key",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EnvironmentEntitlements"
}
}
}
}
},
"x-os-permissions": "To fetch the entitlements, API Client needs the **Stage > View stage** permission in the target stage.\nTo additionally fetch the add-ons, API Client also needs the **Subscriptions > View subscription** permission."
}
},
"/environments/{environmentKey}/entitlements/usage": {
"get": {
"tags": [],
"summary": "Retrieves usage data for entitlements in a specific environment.",
"description": "Filter by entitlement, date range, and aggregation.\n\nTo fetch the usage, API Client needs the **Stage > View stage** and **Subscriptions > View subscription** permissions in the target stage.",
"operationId": "Subscription_GetEnvironmentUsage",
"parameters": [
{
"name": "environmentKey",
"in": "path",
"description": "Environment key",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "granularity",
"in": "query",
"description": "Data granularity (summary, hour, day, month). Defaults to summary.",
"schema": {
"type": "string",
"default": "summary"
}
},
{
"name": "since",
"in": "query",
"description": "Start date for usage data (ISO 8601 format)",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "End date for usage data (ISO 8601 format)",
"schema": {
"type": "string"
}
},
{
"name": "entitlementIds",
"in": "query",
"description": "Optional comma-separated entitlement IDs. Valid values: applicationObjects, maxComputeReplicas, maxDbCompute, maxDbStorage, maxCustomCodeTotalDuration, agentExecutions, internalUsers, externalUsers",
"schema": {
"type": "string"
}
},
{
"name": "aggregations",
"in": "query",
"description": "Optional comma-separated aggregation functions. Valid values: Total, Max, P95, P90",
"schema": {
"type": "string"
}
},
{
"name": "assetKeys",
"in": "query",
"description": "Optional comma-separated asset keys (GUIDs) to filter results",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntitlementUsageItemListResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"x-os-permissions": "To fetch the usage, API Client needs the **Stage > View stage** and **Subscriptions > View subscription** permissions in the target stage."
}
},
"/organization/configurations": {
"get": {
"tags": [],
"summary": "Retrieves information of the organization configurations.",
"description": "Read-only view of organization settings.\n\nAPI Client needs the **Subscriptions > View subscription** permission.",
"operationId": "Subscription_GetOrganizationConfigurations",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationConfigurations"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"x-os-permissions": "API Client needs the **Subscriptions > View subscription** permission."
},
"patch": {
"tags": [],
"summary": "Patches editable organization configurations.",
"description": "Patches editable organization configurations.\n\nAPI Client needs the **Subscriptions > Manage subscription** permission to change organization configurations.",
"operationId": "Subscription_PatchOrganizationConfigurations",
"requestBody": {
"description": "Entitlement information",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/OrganizationConfigurations"
}
],
"description": "Represents the configurations for the Organization."
}
},
"application/*+json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/OrganizationConfigurations"
}
],
"description": "Represents the configurations for the Organization."
}
}
}
},
"responses": {
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"200": {
"description": "OK"
}
},
"x-os-permissions": "API Client needs the **Subscriptions > Manage subscription** permission to change organization configurations."
}
},
"/organization/entitlements": {
"get": {
"tags": [],
"summary": "Retrieves information on the entitlements for the organization.",
"description": "Entitlements and add-ons are shown with sufficient permissions\n\nTo fetch the entitlements, API Client needs at least one permission.\nTo additionally fetch the add-ons and subscription details, API Client also needs the **Subscriptions > View subscription** permission.",
"operationId": "Subscription_GetOrganizationEntitlements",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationEntitlements"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"x-os-permissions": "To fetch the entitlements, API Client needs at least one permission.\nTo additionally fetch the add-ons and subscription details, API Client also needs the **Subscriptions > View subscription** permission."
}
},
"/organization/entitlements/usage": {
"get": {
"tags": [],
"summary": "Retrieves usage data for entitlements for the organization.",
"description": "Filter by entitlement, date range, and aggregation.\n\nAPI Client needs the **Subscriptions > View subscription** permission.",
"operationId": "Subscription_GetOrganizationUsage",
"parameters": [
{
"name": "granularity",
"in": "query",
"description": "Data granularity (summary, hour, day, month). Defaults to summary.",
"schema": {
"type": "string",
"default": "summary"
}
},
{
"name": "since",
"in": "query",
"description": "Start date for usage data (ISO 8601 format)",
"schema": {
"type": "string"
}
},
{
"name": "to",
"in": "query",
"description": "End date for usage data (ISO 8601 format)",
"schema": {
"type": "string"
}
},
{
"name": "entitlementIds",
"in": "query",
"description": "Optional comma-separated entitlement IDs. Valid values: appAnalyticsStreamLimit, applicationObjects, internalUsers, externalUsers",
"schema": {
"type": "string"
}
},
{
"name": "aggregations",
"in": "query",
"description": "Optional comma-separated aggregation functions. Valid values: Total, Max, P95, P90",
"schema": {
"type": "string"
}
},
{
"name": "assetKeys",
"in": "query",
"description": "Optional comma-separated asset keys (GUIDs) to filter results",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntitlementUsageItemListResponse"
}
}
}
},
"401": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
}
}
},
"x-os-permissions": "API Client needs the **Subscriptions > View subscription** permission."
}
}
},
"components": {
"schemas": {
"Addon": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Internal name (internal identifier of the Add-on, visible in APIs only).",
"nullable": true
},
"name": {
"type": "string",
"description": "Name of the Add-on.",
"nullable": true
},
"description": {
"type": "string",
"description": "Description of the Add-on that explains the purpose.",
"nullable": true
},
"documentationUrl": {
"type": "string",
"description": "Documentation URL for the Add-on.",
"nullable": true
},
"dataType": {
"allOf": [
{
"$ref": "#/components/schemas/DataType"
}
],
"description": "Data type of the value associated with the addon, one of [\"bool\", \"float\", \"str\", \"int\"].",
"nullable": true
},
"value": {
"type": "string",
"description": "Value associated with the Add-on. A null value means not subscribed.",
"nullable": true
},
"startDate": {
"type": "string",
"description": "Date when the Add-on starts to be available.",
"nullable": true
},
"endDate": {
"type": "string",
"description": "Date when the Add-on expires (e.g. trials or time-bound Add-ons).",
"nullable": true
},
"unit": {
"type": "string",
"description": "Unit type of the value (e.g. gigabyte, terabyte, second, minute, hour).",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents the Add-on information."
},
"DataType": {
"enum": [
"Bool",
"Float",
"Str",
"Int"
],
"type": "string",
"description": "Data type of the value of an addon or entitlement."
},
"Entitlement": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Internal identifier of the entitlement, visible in APIs only.",
"nullable": true
},
"name": {
"type": "string",
"description": "Name of the entitlement.",
"nullable": true
},
"description": {
"type": "string",
"description": "Description of the entitlement.",
"nullable": true
},
"documentationUrl": {
"type": "string",
"description": "Entitlement documentation URL.",
"nullable": true
},
"value": {
"type": "string",
"description": "A value that is assigned to the entitlement, overriding the default value.",
"nullable": true
},
"dataType": {
"allOf": [
{
"$ref": "#/components/schemas/DataType"
}
],
"description": "Data type of the value associated with the entitlement , one of [\"bool\", \"float\", \"str\", \"int\"].",
"nullable": true
},
"unit": {
"type": "string",
"description": "Unit type of the value (e.g. gigabyte, terabyte, second, minute, hour).",
"nullable": true
},
"kind": {
"type": "string",
"description": "Indicates the kind of the entitlement. This is an open list with current values of (feature, limit, other). New values should be treated the same as \"other\".",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents the Entitlement information."
},
"EntitlementUsageItem": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Entitlement identifier (e.g., \"applicationObjects\").",
"nullable": true
},
"name": {
"type": "string",
"description": "Human-readable name of the entitlement.",
"nullable": true
},
"aggregation": {
"type": "string",
"description": "Aggregation function applied (e.g., \"avg\", \"max\", \"total\").",
"nullable": true
},
"lastUpdatedDate": {
"type": "string",
"description": "Last time this usage data was updated.",
"format": "date-time",
"nullable": true
},
"usage": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UsageDataPoint"
},
"description": "Time series of usage data points.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents usage data for a single entitlement type."
},
"EntitlementUsageItemListResponse": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EntitlementUsageItem"
},
"description": "List of results.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents a response containing a list of results."
},
"EnvironmentEntitlements": {
"type": "object",
"properties": {
"addons": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Addon"
},
"description": "List of addOns in an environment",
"nullable": true
},
"entitlements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Entitlement"
},
"description": "List of entitlements in an environment",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents the entitlements present in an environment"
},
"OrganizationConfigurations": {
"type": "object",
"properties": {
"areAllEmailDomainsInternal": {
"type": "boolean",
"description": "Defines whether all email user domains are internal or not"
},
"internalEmailDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of email user domains to be considered as internal",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents the configurations for the Organization."
},
"OrganizationEntitlements": {
"type": "object",
"properties": {
"subscriptionStartDate": {
"type": "string",
"description": "Date when the organization first subscribed.",
"format": "date-time",
"nullable": true
},
"subscriptionEndDate": {
"type": "string",
"description": "Date when the organization subscription will end.",
"format": "date-time",
"nullable": true
},
"edition": {
"type": "string",
"description": "Name of the Edition.",
"nullable": true
},
"editionId": {
"type": "string",
"description": "Identifier of the Edition.",
"nullable": true
},
"editionFamilyId": {
"type": "string",
"description": "Identifier of the EditionFamily.",
"nullable": true
},
"activationCode": {
"type": "string",
"description": "Organization Activation Code",
"nullable": true
},
"addons": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Addon"
},
"description": "Collection of the addOns the organization is subscribed to.",
"nullable": true
},
"entitlements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Entitlement"
},
"description": "Collection of the entitlements the organization is entitled to.",
"nullable": true
}
},
"additionalProperties": false,
"description": "Represents the entitlements present in an organization"
},
"PageInfoWithTotals": {
"type": "object",
"properties": {
"count": {
"type": "integer",
"description": "Number of results in the current page.",
"format": "int32"
},
"limit": {
"type": "integer",
"description": "Limit of results per page.",
"format": "int32"
},
"offset": {
"type": "integer",
"description": "Offset of the current page of results.",
"format": "int32"
},
"nextPageOffset": {
"type": "integer",
"description": "Offset of the next page of results. Null when there is no next page.",
"format": "int32",
"nullable": true
},
"totalResults": {
"type": "integer",
"description": "Total of results.",
"format": "int32"
},
"totalPages": {
"type": "integer",
"description": "Total of result pages.",
"format": "int32",
"readOnly": true
}
},
"additionalProperties": false,
"description": "Contains response page information including totals."
},
"ProblemDetails": {
"type": "object",
"properties": {
"type": {
"type": "string",
"description": "A URI reference that identifies the problem type.",
"nullable": true
},
"title": {
"type": "string",
"description": "A short, human-readable summary of the problem.",
"nullable": true
},
"status": {
"type": "integer",
"description": "The HTTP status code applicable to the problem.",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"description": "A human-readable explanation of the error.",
"nullable": true
},
"instance": {
"type": "string",
"description": "A URI that identifies the specific occurrence of the problem.",
"nullable": true
},
"traceId": {
"type": "string",
"description": "This field helps OutSystems support track and investigate specific error occurrences. Providing this identifier when reporting an issue allows for more precise and faster troubleshooting."
},
"errorCode": {
"type": "string",
"description": "This error code serves the purpose to communicate with OutSystems Support and help diagnose errors."
}
},
"description": "A standardized error response as per RFC 7807 (Problem Details for HTTP APIs)."
},
"UnifiedEntitlementAssetRow": {
"type": "object",
"properties": {
"assetKey": {
"type": "string",
"description": "Asset unique identifier (GUID).",
"nullable": true
},
"name": {
"type": "string",
"description": "Asset name.",
"nullable": true
},
"assetType": {
"type": "string",
"description": "Asset type (e.g., \"Application\", \"Library\").",
"nullable": true
},
"value": {
"type": "number",
"description": "Aggregated usage value for this asset.",
"format": "double",
"nullable": true
},
"revision": {
"type": "integer",
"description": "Asset revision number.",
"format": "int32",
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/outsystems/refs/heads/main/openapi/outsystems-subscription-api-v1-openapi.json