Paigo Measurements API

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: {}