openapi: 3.0.0
info:
title: Paigo Customers Dimensions API
description: "\nFor developer documentation of the platform, please visit https://docs.paigo.tech.\n\n## Authentication\nPaigo API supports **bearer token** as the authentication method.\nSteps to set up authentication:\n1. Sign up with Paigo platform and get **client id** and **client secret**.\n2. Make a POST request to the auth endpoint `https://auth.paigo.tech/oauth/token` with the following body:\n```json\n{\n audience: 'https://qnonyh1pc7.execute-api.us-east-1.amazonaws.com',\n grant_type: 'client_credentials',\n client_id: <your client id>,\n client_secret: <your client secret>\n}\n```\nAdditionally verify that the following headers are set by the client you are using: \n```json\n{\n \"Content-Type\": \"application/json\"\n}\n```\n\n3. Use the access token in the response to make requests to the Paigo API. Here is an example of the response: \n```json \n{\n access_token: <your access token>,\n expires_in: 86400,\n token_type: 'Bearer' \n}\n```\n4. To use Paigo API, add in the header of your request:\n```json\n{\n Authorization: \"Bearer <your access token>\"\n}\n```\n\n## API Endpoints\nPaigo API has the following endpoint:\n- Production Environment API: `https://api.prod.paigo.tech`\n "
version: v1.10
contact: {}
servers:
- url: https://api.prod.paigo.tech
description: Product Environment API
tags:
- name: Dimensions
description: Manage dimensions in Paigo.
paths:
/dimensions:
get:
operationId: Get all dimensions
summary: ''
description: List all dimensions created in this account
parameters: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadDimensionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Dimensions
security:
- bearer: []
post:
operationId: Create a dimension
summary: ''
description: 'Create a dimension
<br><br>
<a href="https://docs.paigo.tech/model-pricing-and-package/pricing-modeling-guide/single-dimension-pay-as-you-go-pricing">See an example dimension for pay as you go pricing here</a>'
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDimensionDto'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDimensionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Dimensions
security:
- bearer: []
/dimensions/{dimensionId}:
get:
operationId: Get a dimension by ID
summary: ''
description: Fine a dimension
parameters:
- name: dimensionId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `22372d1d-1c0c-40e0-8167-af0b4f5c82f6`'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadDimensionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Dimension Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'No Dimensions found with ID: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'No Dimensions found with ID: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Dimensions
security:
- bearer: []
put:
operationId: Update a dimension
summary: ''
description: Update a dimension
parameters:
- name: dimensionId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `22372d1d-1c0c-40e0-8167-af0b4f5c82f6`'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDimensionDto'
responses:
'200':
description: Dimension Updated
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDimensionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Dimension Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'No Dimensions found with ID: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'No Dimensions found with ID: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Dimensions
security:
- bearer: []
delete:
operationId: Delete a dimension
summary: ''
description: Delete a dimension
parameters:
- name: dimensionId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `22372d1d-1c0c-40e0-8167-af0b4f5c82f6`'
schema:
type: string
responses:
'200':
description: Dimension Deleted
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Dimension Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'No Dimensions found with ID: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6'
error:
type: string
description: The error name
example: Not Found
statusCode:
type: number
description: The HTTP status code
example: 404
externalDocs:
description: MDN Documentation Reference
url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
example:
message: 'No Dimensions found with ID: 22372d1d-1c0c-40e0-8167-af0b4f5c82f6'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
'409':
description: Conflict - Can't delete dimension
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- 'true'
description: An error message containing the reason why the dimension cannot be deleted.<br><br> Dimensions cannot be deleted if they are in use by active offerings.
example: 'Cannot Delete Dimensions when they are attached to Offerings, remove dimensions from offerings before deleting. Current OfferingIds using the dimension: 693f9f08-202e-4377-b415-9767a59ce4cd'
tags:
- Dimensions
security:
- bearer: []
components:
schemas:
CountBasedConsumptionUnit:
type: object
properties:
unit:
type: string
enum:
- count-based
description: A dimensionless unit for a dimension of type count-based
examples:
- count-based
type:
type: string
enum:
- count
description: A string that indicates the type of consumption unit
required:
- unit
- type
CreateDimensionResponse:
type: object
properties:
message:
type: string
description: A human readable message describing the outcome of the operation
example: This is a sample API message. The exact message may vary based on the API behavior
dimensionId:
type: string
description: 'The unique identifier assigned by Paigo.
<br><br>
Example: `"fcb1fa34-8f11-4832-80f2-464cbc7a8546"`'
example: fcb1fa34-8f11-4832-80f2-464cbc7a8546
required:
- message
- dimensionId
TimeBasedConsumptionUnit:
type: object
properties:
unit:
enum:
- second
- minute
- hour
- day
type: string
description: A unit of time for a dimension of type time-based
examples:
- second
- minute
- hour
- day
type:
type: string
enum:
- time
description: A string that indicates the type of consumption unit
required:
- unit
- type
DatastoreAccessInformationResponse:
type: object
properties:
platform:
description: Underlying resource type which paigo connects to. <br><br> Example `"s3"`
enum:
- s3
- kafka
type: string
examples:
- s3
consumerDeploymentParameters:
description: The access information and configuration for deploying a datastore consumer by Paigo. Use this field in a case where Paigo is deploying a consumer and you want to provide the access information for the datastore.
oneOf:
- $ref: '#/components/schemas/KafkaDeploymentParametersDto'
ingestion:
type: string
description: The Ingestion endpioint for data to be dropped off at.
dlq:
type: string
description: The DLQ endpoint for data which has failed to be processed.
iamRoleArn:
type: string
description: The IAM role associated with the endpoints for access management
externalId:
type: string
description: The externalId associated with the endpoints
region:
type: string
description: The region associated with the endpoints, defaults to `us-east-1`
accountId:
type: string
description: 'The Unqiue ID for your cloud account.
<br><br>
Example `"623673123435"`'
example: '623673123435'
required:
- platform
- ingestion
- dlq
ReadDimensionResponse:
type: object
properties:
message:
type: string
description: A human readable message describing the outcome of the operation
example: This is a sample API message. The exact message may vary based on the API behavior
data:
description: Array of dimensions
minItems: 0
type: array
items:
$ref: '#/components/schemas/ReadDimensionResponseData'
required:
- message
- data
DimensionTierDto:
type: object
properties:
tierName:
type: string
description: 'The name of the tier as it would appear on the invoice. If Tier name is not included, no `tierName` will be displayed on the invoice, and it will follow the default line item naming standard. See: https://docs.paigo.tech/invoicing-and-payment/issue-invoice/automatic-line-item-formatting
<br><br>
Example: `"Tier 1"`'
example: Tier 1
upperBound:
type: string
description: 'The upper limit of the tier, inclusive. If the upperBound is set to "inf", it must have the highest `tierPosition`. Additionally, the `upperBound` must be a multiple of the `usageIncrement`
on the dimension. For example, if the `usageIncrement` is 100, the `upperBound` must be 100, 200, 300, etc. The `upperBound` cannot overlap with previous tiers, so tier 1''s `upperBound` must be smaller than tier 2''s.
<br><br>
Example: `"100"`'
example: '100'
unitPrice:
type: string
description: 'The unit price of the tier.
<br><br>
Example: `"10"`'
example: '10'
tierPosition:
type: string
description: 'The position of the tier. The first tier must have a `tierPosition` of 1, the second tier must have a `tierPosition` of 2, etc. Order of the tiers is determined by the `tierPosition`.
<br><br>
Example: `"1"`'
example: '1'
required:
- upperBound
- tierPosition
BasicResponseDTO:
type: object
properties:
message:
type: string
description: A human readable message describing the outcome of the operation
example: This is a sample API message. The exact message may vary based on the API behavior
required:
- message
InfrastructureAccessInformation:
type: object
properties:
iamRoleArn:
type: string
description: 'The IAM role created by SaaS business and can be by Paigo AWS account to measure usage.
<br><br>
Example `"arn:aws:iam::214826386939:role/paigo-scraper"`'
example: arn:aws:iam::214826386939:role/paigo-scraper
externalId:
type: string
description: 'The Optional ExternalId associated with the IAM role.
<br><br>
Example `"123456789"`'
example: '123456789'
externalDocs:
description: Read more about why externalIds are important
url: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html
cloudPlatform:
type: string
enum:
- aws
example: aws
description: Cloud infrastructure platform <br><br> Example `"aws"`
region:
type: string
description: 'Supported region of the infrastructure
Example `"us-east-1"`'
example: us-east-1
resourceType:
type: string
enum:
- ebssnapshot
- ebs
- k8spod
- ec2
- ec2egress
- usageData
example: ebs
description: Underlying resource type which Paigo measures usage for. <br><br> Example `"ec2"`
required:
- iamRoleArn
- cloudPlatform
- region
- resourceType
DatabasedConsumptionUnit:
type: object
properties:
unit:
enum:
- byte
- kilobyte
- megabyte
- gigabyte
- kibibyte
- mebibyte
- gibibyte
type: string
description: A unit of data for a dimension of type data-based
examples:
- byte
- kilobyte
- megabyte
- gigabyte
type:
type: string
enum:
- data
description: A string that indicates the type of consumption unit
required:
- unit
- type
KafkaDeploymentParametersDto:
type: object
properties:
securityMechanism:
type: string
externalDocs:
url: https://docs.confluent.io/platform/current/kafka/authentication_sasl/authentication_sasl_plain.html#sasl-plain-overview
example: PLAIN
description: 'The security protocol to use when connecting to the Kafka cluster. Defaults to `PLAIN`. Note this is not PLAINTEXT. PLAIN is the SASL_PLAIN protocol. <br><br> Example: `"PLAIN"`'
username:
type: string
description: 'The username to use when connecting to the Kafka cluster. <br><br> Example: `"admin"`'
example: admin
password:
type: string
description: 'The password to use when connecting to the Kafka cluster. <br><br> Example: `"hunter2"`'
example: hunter2
bootstrapServerEndpoint:
type: string
description: 'The endpoint of the Kafka cluster to connect to. <br><br> Example: `"kafka.paigo.tech"`'
example: kafka.paigo.tech
topic:
type: string
description: 'The topic to subscribe to. <br><br> Example: `"test-topic"`'
example: '"test-topic"'
dlqTopic:
type: string
description: 'The DLQ topic to write to when a message fails to be processed. <br><br> Example: `"dlq-topic"`'
example: '"dlq-topic"'
required:
- securityMechanism
- username
- password
- bootstrapServerEndpoint
- topic
- dlqTopic
ReadMeasurementResponseData:
type: object
properties:
measurementMode:
type: string
enum:
- infrastructureBased
- agentBased
- datastoreBased
example: infrastructureBased
description: The measurement method. See <a href="https://docs.paigo.tech/measure-usage-and-collect-data/measure-and-collect-usage-data-at-production-scale">Measure and Collect Usage Data at Production Scale</a> for more information. <br><br> Example `"agentBased"`
measurementConfiguration:
description: Configuration for the measurement method.
oneOf:
- $ref: '#/components/schemas/InfrastructureAccessInformation'
- $ref: '#/components/schemas/AgentAccessInformation'
- $ref: '#/components/schemas/DatastoreAccessInformationResponse'
measurementName:
type: string
description: 'The human readable name of the measurement
<br><br>
Example `"EBS Usage"`'
example: EBS Usage
measurementId:
type: string
description: 'Unique identifier assigned by Paigo.
<br><br>
Example `"de388932-a7e1-11ed-afa1-0242ac120002"`'
example: de388932-a7e1-11ed-afa1-0242ac120002
required:
- measurementMode
- measurementConfiguration
- measurementId
UpdateDimensionDto:
type: object
properties:
dimensionName:
type: string
description: 'A friendly, human-readable name for the dimension.
<br><br>
Example `"API Call"`'
examples:
- API Call
- CPU Hours
- Provisioned Capacity
consumptionUnit:
description: 'Consumption unit of the dimension.
Paigo supports three types of consumption units: count-based, time-based, and data-based.
Supported values for each consumption unit type are listed below. <br>
- count: `"count-based"` <br>
- time-based: `"second"`, `"minute"`, `"hour"`, `"day"` <br>
- data-based: `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"` <br>
This field accepts a JSON object with the following schema: <br>
```
{ "type": "typeName", "unit": "unitName" }
```
<br><br>
Example: <br>
`{ "type": "count", "unit": "count-based" }` <br>
`{ "type": "time", "unit": "hour" }` <br>
`{ "type": "data", "unit": "byte" }` <br>'
oneOf:
- $ref: '#/components/schemas/CountBasedConsumptionUnit'
- $ref: '#/components/schemas/TimeBasedConsumptionUnit'
- $ref: '#/components/schemas/DatabasedConsumptionUnit'
usageIncrement:
type: string
description: 'The minimum increment for usage amount.
As an example, if usage increment is 1 Hour job execution time,
then 1 Hour and 5 Minutes execution time may be calculated as 1 Hour or 2 Hours,
depending on the rounding algorithm field of the dimension.
<br><br>
Example `1`'
example: '24'
externalDocs:
description: See how usage increment is used in the billing process
url: https://docs.paigo.tech/model-pricing-and-package/define-product-metrics#understand-how-billing-aggregation-works
usageEntitlement:
description: 'Used with Subscription Tier Offering type. <br>
SaaS customers subscribed to a subscription tier are entitled to use the amount of product
with regard to the dimension up to the value specified in this field.
For example, a subscription tier may entitle subscribers to make up to 1,000,000 API requests.'
oneOf:
- type: number
description: The number of units that the customer is entitled to use, must be greater than or equal to 0
example: 1000000
- type: string
format: inf
description: The customer is entitled to use the product's dimension without any limit
example: inf
examples:
- inf
- 1000000
aggregationInterval:
description: Time interval to aggregate dimension usage data for billing. <br><br>
enum:
- none
- hour
- day
- month
type: string
example: hour
default: hour
externalDocs:
description: See how aggregation interval is used in the billing process
url: https://docs.paigo.tech/model-pricing-and-package/define-product-metrics#understand-how-billing-aggregation-works
aggregationMethod:
description: 'The algorithm to aggregate raw usage data for billing.
<br><br>'
enum:
- sum
- max
- min
- count
- average
- last
type: string
example: sum
default: max
externalDocs:
description: See how aggregation method is used in the billing process
url: https://docs.paigo.tech/model-pricing-and-package/define-product-metrics#understand-how-billing-aggregation-works
measurementId:
type: string
description: The unique identifier of the measurement attached to the dimension.
example: 5f7d1e3a-3b2d-4b0a-8b9a-5b9b5c9b5c9b
tiers:
description: In order to remove tiers from a dimension, set the tiers array to `null`. The value passed to the tiers array will completely replace the existing tiers array.
type: array
items:
$ref: '#/components/schemas/DimensionTierDto'
rounding:
type: string
description: 'The rounding algorithm that is used to calculate the amount of usage increment.
Ceiling algorithm rounds up, floor algorithm rounds down, the round algrogrithm rounds to the nearest whole integer rounding half away from zero.
As an example, if usage increment is 1 Hour job execution time,
then 1 Hour and 5 Minutes execution time may be calculated as 2 Hours for ceiling algorithm, 1 Hour for floor algorithm, and 1 Hour for round algorithm.
depending on the rounding algorithm field of the dimension.
<br><br>'
enum:
- round
- floor
- ceiling
overageAllowed:
type: string
description: 'Used with Subscription Tier Offering type. <br>
When the usage entitlement is specified,
this field decides if allowing SaaS customers to use more than entitled amount of the product dimension.'
enum:
- 'true'
- 'false'
consumptionPrice:
type: string
description: 'The unit price of dimension.
Numerical values are represented as strings to avoid precision loss.
<br><br>'
example: '20.00'
sampleType:
type: string
description: 'The sample type used for the data. Gauge is a value that can go up or down. <br>
Currently set to gauge by default on all dimensions.'
example: gauge
enum:
- gauge
- continious
paymentSchedule:
type: string
description: 'The payment schedule for the dimension. Determines when billing should occur for a dimension. `upfront` will occur the moment a customer is enrolled in an offering containing the dimension. `arrear` will occur at the end of the billing cycle.
`upfront` is used for dimensions like purchasing a subscription, or seats for a plan. Where as `arrear` is used for dimensions like usage based billing. Dimensions can be comingled in an offering, so you can have a dimension that is billed `upfront` and another that is billed `arrear`.
Optional, if not included will be `arrear` by default.'
example: upfront
enum:
- upfront
- arrear
metadata:
type: object
description: 'An optional key-value map of additional metadata to associate with the dimensions.
such as environment, purpose, owner, developer, contract number,
or any arbitrary data to be associated with this usage record. Additionally, if `null` is passed for any value in the metadata object it will be removed.
To entirely remove the metadata object, pass null to the metadata field.
<br><br>
Example `{"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe", "workspaceId": null}`
<br><br>
In the above example, the `workspaceId` metadata key will be removed from the dimension. To remove all fields pass the following.
<br><br>
Example `"metadata": null`'
tiersGroupByMetadata:
description: Used to group tiers by metadata, meaning instead of grouping by the dimensionId for usage Paigo will group requests with the metadata passed in on the usage request. Exclusive with standard `consumptionPrice`, `entitlement`, `overageAllowed` and `tiers` fields.
type: array
items:
$ref: '#/components/schemas/DimensionTiersGroupByMetadataDto'
DimensionTiersGroupByMetadataDto:
type: object
properties:
metadataGroups:
type: object
description: 'The metadata groups to group the tiers by. A collection of key value pairs. metadata groups are used alongside the usage passed in to define more accurately how to break up price and usage for a dimension.
<br><br>
Example: `{ "instanceType": "t3.medium", "region": "us-east-1", "deployment": "production"}`'
tiers:
type: array
items:
$ref: '#/components/schemas/DimensionTierDto'
required:
- metadataGroups
- tiers
ReadDimensionResponseData:
type: object
properties:
dimensionName:
type: string
description: 'A friendly, human-readable name for the dimension.
<br><br>
Example `"API Call"`'
examples:
- API Call
- CPU Hours
- Provisioned Capacity
consumptionUnit:
description: 'Consumption unit of the dimension.
Paigo supports three types of consumption units: count-based, time-based, and data-based.
Supported values for each consumption unit type are listed below. <br>
- count: `"count-based"` <br>
- time-based: `"second"`, `"minute"`, `"hour"`, `"day"` <br>
- data-based: `"byte"`, `"kilobyte"`, `"megabyte"`, `"gigabyte"` <br>
This field accepts a JSON object with the following schema: <br>
```
{ "type": "typeName", "unit": "unitName" }
```
<br><br>
Example: <br>
`{ "type": "count", "unit": "count-based" }` <br>
`{ "type": "time", "unit": "hour" }` <br>
`{ "type": "data", "unit": "byte" }` <br>'
oneOf:
- $ref: '#/components/schemas/CountBasedConsumptionUnit'
- $ref: '#/components/schemas/TimeBasedConsumptionUnit'
- $ref: '#/components/schemas/DatabasedConsumptionUnit'
usageIncrement:
type: string
description: 'The minimum increment for usage amount.
As an example, if usage increment is 1 Hour job execution time,
then 1 Hour and 5 Minutes execution time may be calculated as 1 Hour or 2 Hours,
depending on the rounding algorithm field of the dimension.
<br><br>
Example `1`'
example: '24'
externalDocs:
description: See how usage increment is used in the billing process
url: https://docs.paigo.tech/model-pricing-and-package/define-product-metrics#understand-how-billing-aggregation-works
usageEntitlement:
description: 'Used with Subscription Tier Offering type. <br>
SaaS customers subscribed to a subscription tier are entitled to use the amount of product
with regard to the dimension up to the value specified in this field.
For example, a subscription tier may entitle subscribers to make up to 1,000,000 API requests.'
oneOf:
- type: number
description: The number of units that the customer is entitled to use, must be greater than or equal to 0
example: 1000000
- type: string
format: inf
description: The customer is entitled to use the product's dimension without any limit
example: inf
examples:
- inf
- 1000000
aggregationInterval:
description: Time interval to aggregate dimension usage data for billing. <br><br>
enum:
- none
- hour
- day
- month
type: string
example: hour
default: hour
externalDocs:
description: See how aggregation interval is used in the billing process
url: https://docs.paigo.tech/model-pricing-and-package/define-product-metrics#understand-how-billing-aggregation-works
aggregationMethod:
description: 'The algorithm to aggregate raw usage data for billing.
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paigo/refs/heads/main/openapi/paigo-dimensions-api-openapi.yml