Paigo Measurements API
Manage measurements in Paigo. See Measure and Collect Usage Data at Production Scale for more information.
OpenAPI Specification
openapi: 3.0.0
info:
title: Paigo Customers Measurements 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: Measurements
description: Manage measurements in Paigo. <br><br> 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.
paths:
/measurements:
get:
operationId: Get all measurements
summary: ''
description: List all measurements created
parameters: []
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadMeasurementConfigResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Measurements
security:
- bearer: []
post:
operationId: Create a measurement
summary: ''
description: Create a measurement
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMeasurementConfigDto'
responses:
'201':
description: Measurement Created
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMeasurementConfigurationResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Measurements
security:
- bearer: []
/measurements/{measurementId}:
get:
operationId: Get a measurement by ID
summary: ''
description: Find a measurement
parameters:
- name: measurementId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `a65ae317-e940-44cc-b570-cc74d1897c36`'
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ReadMeasurementConfigResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Measurement Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Measurement with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
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: 'Measurement with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Measurements
security:
- bearer: []
put:
operationId: Update a measurement
summary: ''
description: Update a measurement
parameters:
- name: measurementId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `a65ae317-e940-44cc-b570-cc74d1897c36`'
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMeasurementConfigDto'
responses:
'200':
description: Measurement Updated
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMeasurementConfigurationResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Measurement Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Measurement with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
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: 'Measurement with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Measurements
security:
- bearer: []
delete:
operationId: Delete a measurement
summary: ''
description: Delete a measurement
parameters:
- name: measurementId
required: true
in: path
description: 'The unique identifier assigned by Paigo.<br><br> Example: `a65ae317-e940-44cc-b570-cc74d1897c36`'
schema:
type: string
responses:
'200':
description: Measurement deleted
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteMeasurementConfigResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'404':
description: Measurement Not Found
content:
application/json:
schema:
type: object
properties:
message:
type: string
description: The error message
example: 'Measurement with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
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: 'Measurement with ID: 807867e0-26ca-4831-846b-a670224db055 not found'
error: Not Found
statusCode: 404
required:
- message
- error
- statusCode
tags:
- Measurements
security:
- bearer: []
components:
schemas:
DeleteMeasurementConfigResponse:
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
measurementId:
type: string
description: 'The unique identifier assigned by Paigo
<br><br>
Example: `"193b6967-1783-434f-85cb-a6fc4e1e385b"`'
example: 193b6967-1783-434f-85cb-a6fc4e1e385b
required:
- message
- measurementId
UpdateMeasurementConfigDto:
type: object
properties:
measurementMode:
type: string
enum:
- infrastructureBased
- agentBased
- datastoreBased
example: infrastructure
measurementConfiguration:
description: Configuration for the measurement method.
oneOf:
- $ref: '#/components/schemas/UpdateInfrastructureAccessInformation'
- $ref: '#/components/schemas/UpdateAgentAccessInformation'
- $ref: '#/components/schemas/UpdateDatastoreAccessInformation'
measurementName:
type: string
description: A friendly, human-readable name of the measurement.
required:
- measurementMode
- measurementName
CreateMeasurementConfigDto:
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/DatastoreAccessInformation'
measurementName:
type: string
description: 'The human readable name of the measurement
<br><br>
Example `"EBS Usage"`'
example: EBS Usage
required:
- measurementMode
- measurementConfiguration
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
UpdateDatastoreAccessInformation:
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'
accountId:
type: string
description: 'The Unqiue ID for your cloud account.
<br><br>
Example `"623673123435"`'
example: '623673123435'
UpdateInfrastructureAccessInformation:
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"`
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
UpdateAgentAccessInformation:
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
hostingPlatform:
type: string
enum:
- k8spod
example: k8spod
description: Hosting platform of SaaS application
CreateMeasurementConfigurationResponse:
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
externalId:
type: string
description: 'The externalId to be used with the IAM role.
<br><br>
Example: `"1234567890abc"`'
example: 1234567890abc
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
measurementId:
type: string
description: 'Unique identifier assigned by Paigo
<br><br>
Example: `"a65ae317-e940-44cc-b570-cc74d1897c36"`'
example: a65ae317-e940-44cc-b570-cc74d1897c36
iamRoleArn:
type: string
description: 'The IAM role which can be assumed to pass data on a Paigo-hosted datastore.
<br><br>
Example: `"arn:aws:iam::123456789012:role/paigo-datastore-role"`'
example: arn:aws:iam::123456789012:role/paigo-datastore-role
ingestion:
type: string
description: 'The URL of the ingestion endpoint associated with the datastore measurement
<br><br>
Example: `"s3://paigo-datastore-dump-bucket/"`'
example: s3://paigo-datastore-dump-bucket/
dlq:
type: string
description: 'The URL of the DLQ endpoint associated with the datastore measurement
<br><br>
Example: `"s3://paigo-datastore-dlq-bucket/"`'
example: s3://paigo-datastore-dlq-bucket/
required:
- message
- measurementId
DatastoreAccessInformation:
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'
accountId:
type: string
description: 'The Unqiue ID for your cloud account.
<br><br>
Example `"623673123435"`'
example: '623673123435'
required:
- platform
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
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
ReadMeasurementConfigResponse:
type: object
properties:
message:
type: string
description: The human readable message from the Read Measurement API
example: This is a sample API message. The exact message may vary based on the API behavior
examples:
- Found Measurements
- No Measurements Found
data:
description: Array of measurements
minItems: 0
type: array
items:
$ref: '#/components/schemas/ReadMeasurementResponseData'
required:
- message
- data
AgentAccessInformation:
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
hostingPlatform:
type: string
enum:
- k8spod
example: k8spod
description: Hosting platform of SaaS application
required:
- iamRoleArn
- hostingPlatform
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: oauth2
in: Header
description: Use bearer token to authenticate `Bearer <your access token>`
flows:
clientCredentials:
tokenUrl: https://auth.paigo.tech/oauth/token
scopes: {}