OpenAPI Specification
openapi: 3.0.0
info:
title: Paigo Customers Usage 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: Usage
description: Measure and collect usage data.
paths:
/usage:
post:
operationId: Collect usage data
summary: ''
description: 'Collect usage data by API-based 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 full documentation on Paigo <b>Usage Measurement and Collection</b>.'
parameters:
- name: invoice
required: false
in: query
description: The invoice query parameter is used to create an invoice for the usage data body. It can _only_ be used with dimensions that have an `upfront` payment schedule and `last` aggregation method. If the dimension does not have these properties, the invoice will not be created and a `400` status code will be returned. Additionally, the customer for the usage must be actively enrolled in an offering in order to make use of the automated invoice, otherwise a `400` error will be returned. The body will not be loaded into the database on any `400` error. <br/><br/> The invoice created is independent of any `tiers`, or `entitlement` associated with the dimension, and will be created for the exact usage data sent in. <br/><br/> The invoice will be created for the difference between the usage data sent in, and the most recent usage data for the dimension. If the usage data sent in is less than the most recent usage data, a zero quantity line item will be created. For example if the most recent usage data for a dimension is `5`, and the usage data sent in is `3`, a zero quantity line item will be created. If the usage data sent in is `7`, a `2` quantity line item will be created.
example: true
schema:
type: boolean
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUsageDto'
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/BasicResponseDTO'
tags:
- Usage
security:
- bearer: []
components:
schemas:
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
CreateUsageDto:
type: object
properties:
dimensionId:
type: string
description: 'The unique identifier of the dimension this usage record is associated with.
<br><br>
Example: `''da9611bd-e0f3-4c0d-a754-fda5be730872''`'
timestamp:
type: string
description: 'The timestamp of usage record in <a href="https://ijmacd.github.io/rfc3339-iso8601/">RFC3339</a>
format with a 4-digit year.
This is the time the usage occurred, or the end of the usage period.
<br><br>
Example: `"2023-02-08T19:24:10Z"`'
customerId:
type: string
description: 'The unique identifier of the customer this usage record attributes to.
<br><br>
Example: `"e8366954-6f36-47e9-8431-ac95f88b5cc7"`'
recordValue:
type: string
description: 'The amount of the usage on this record.
Numerical values are represented as strings to avoid precision loss.
<br><br>
Example: `"0.87"`'
metadata:
type: object
description: 'An optional key-value map of additional metadata to associate with this usage record.
Additional metadata to be stored on the usage record,
such as environment, purpose, owner, developer, contract number,
or any arbitrary data to be associated with this usage record.
Metadata can be used for analytics purpose.
<br><br>
Example `{"environment": "staging", "purpose": "proof-of-concept", "owner": "John Doe"}`'
required:
- dimensionId
- timestamp
- customerId
- recordValue
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: {}