API Reference

Complete reference for all Automatum API endpoints.

Base URL

https://api.automatum.io/api/v1

Authentication

All endpoints require OAuth 2.0 authentication. See the Authentication Guide for details.

bash

Authorization: Bearer YOUR_ACCESS_TOKEN

Response Format

Success Response

json

{
  "code": 200,
  "data": {
    // Response data
  }
}

Error Response

json

{
  "code": 400,
  "message": "Error description",
  "errors": [
    {
      "field": "fieldName",
      "message": "Field-specific error"
    }
  ]
}

Customers

List Customers

Get a paginated list of customers for your organization.

http

GET /api/v1/customers

Required Scope: read:customers

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `active`, `inactive`
`vendor`	string	Filter by vendor: `aws`, `azure`
`search`	string	Search by name or email

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/customers?page=1&limit=20&status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": [
    {
      "id": "cust_1a2b3c4d",
      "organizationId": "org_5e6f7g8h",
      "vendor": "aws",
      "awsAccountId": "123456789012",
      "email": "customer@example.com",
      "companyName": "Acme Corporation",
      "status": "active",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-01-16T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "pages": 3
  }
}

Get Customer

Get details for a specific customer.

http

GET /api/v1/customers/:id

Required Scope: read:customers

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/customers/cust_1a2b3c4d" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": {
    "id": "cust_1a2b3c4d",
    "organizationId": "org_5e6f7g8h",
    "vendor": "aws",
    "awsAccountId": "123456789012",
    "email": "customer@example.com",
    "companyName": "Acme Corporation",
    "status": "active",
    "entitlements": [
      {
        "id": "ent_9i0j1k2l",
        "listingId": "listing_3m4n5o6p",
        "status": "active"
      }
    ],
    "createdAt": "2026-01-15T10:00:00Z",
    "updatedAt": "2026-01-16T14:30:00Z"
  }
}

Entitlements

List Entitlements

Get a list of all entitlements for your organization.

http

GET /api/v1/entitlements

Required Scope: read:entitlements

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `active`, `expired`, `cancelled`
`customerId`	string	Filter by customer ID
`listingId`	string	Filter by listing ID

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/entitlements?status=active" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": [
    {
      "id": "ent_9i0j1k2l",
      "organizationId": "org_5e6f7g8h",
      "customerId": "cust_1a2b3c4d",
      "listingId": "listing_3m4n5o6p",
      "vendor": "aws",
      "status": "active",
      "startDate": "2026-01-01T00:00:00Z",
      "endDate": "2027-01-01T00:00:00Z",
      "dimensions": [
        {
          "key": "users",
          "value": 100
        }
      ],
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-15T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 89,
    "pages": 5
  }
}

Get Entitlement

Get details for a specific entitlement.

http

GET /api/v1/entitlements/:id

Required Scope: read:entitlements

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/entitlements/ent_9i0j1k2l" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": {
    "id": "ent_9i0j1k2l",
    "organizationId": "org_5e6f7g8h",
    "customerId": "cust_1a2b3c4d",
    "listingId": "listing_3m4n5o6p",
    "vendor": "aws",
    "status": "active",
    "startDate": "2026-01-01T00:00:00Z",
    "endDate": "2027-01-01T00:00:00Z",
    "dimensions": [
      {
        "key": "users",
        "value": 100,
        "description": "Number of users"
      }
    ],
    "history": [
      {
        "action": "created",
        "timestamp": "2026-01-01T00:00:00Z"
      },
      {
        "action": "updated",
        "timestamp": "2026-01-15T10:00:00Z",
        "changes": {
          "dimensions.users": { "from": 50, "to": 100 }
        }
      }
    ],
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-15T10:00:00Z"
  }
}

Private Offers

List Private Offers

Get a list of all private offers for your organization.

http

GET /api/v1/private-offers

Required Scope: read:private-offers

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `draft`, `created`, `accepted`, `expired`
`vendor`	string	Filter by vendor: `aws`, `azure`
`listingId`	string	Filter by listing ID

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/private-offers?status=created" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": [
    {
      "id": "offer_7q8r9s0t",
      "organizationId": "org_5e6f7g8h",
      "listingId": "listing_3m4n5o6p",
      "customerId": "cust_1a2b3c4d",
      "vendor": "aws",
      "status": "created",
      "vendorOfferId": "offer-abc123xyz",
      "details": {
        "summary": {
          "offerName": "Q1 2026 Enterprise Deal",
          "companyName": "Acme Corporation"
        },
        "pricing": {
          "discountPercentage": 20,
          "duration": 12
        }
      },
      "createdAt": "2026-01-10T12:00:00Z",
      "updatedAt": "2026-01-10T12:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 34,
    "pages": 2
  }
}

Get Private Offer

Get details for a specific private offer.

http

GET /api/v1/private-offers/:id

Required Scope: read:private-offers

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/private-offers/offer_7q8r9s0t" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": {
    "id": "offer_7q8r9s0t",
    "organizationId": "org_5e6f7g8h",
    "listingId": "listing_3m4n5o6p",
    "customerId": "cust_1a2b3c4d",
    "vendor": "aws",
    "status": "created",
    "vendorOfferId": "offer-abc123xyz",
    "details": {
      "summary": {
        "offerName": "Q1 2026 Enterprise Deal",
        "companyName": "Acme Corporation",
        "buyerNotifications": [
          {
            "name": "John Doe",
            "email": "john.doe@acme.com"
          }
        ]
      },
      "pricing": {
        "discountPercentage": 20,
        "duration": 12,
        "annualValue": 120000
      },
      "aws": {
        "agreementId": "agmt-xyz789",
        "isReplacement": false
      }
    },
    "createdAt": "2026-01-10T12:00:00Z",
    "updatedAt": "2026-01-10T12:00:00Z"
  }
}

Metering

Submit Metering Data

Submit usage metering data to the marketplace.

http

POST /api/v1/metering

Required Scope: write:metering

Request Body:

Field	Type	Required	Description
`vendor`	string	Yes	Marketplace vendor: `aws` or `azure`
`customerId`	string	Yes	Customer ID
`listingId`	string	Yes	Listing ID
`dimension`	string	Yes	Metering dimension key
`quantity`	number	Yes	Usage quantity (must be positive)
`timestamp`	string	Yes	ISO 8601 timestamp
`idempotencyKey`	string	No	Unique key for deduplication

Example Request:

bash

curl -X POST "https://api.automatum.io/api/v1/metering" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "aws",
    "customerId": "cust_1a2b3c4d",
    "listingId": "listing_3m4n5o6p",
    "dimension": "api_calls",
    "quantity": 1000,
    "timestamp": "2026-01-16T12:00:00Z",
    "idempotencyKey": "metering_20260116_1200_api_calls"
  }'

Example Response:

json

{
  "code": 200,
  "data": {
    "id": "meter_1u2v3w4x",
    "status": "submitted",
    "vendor": "aws",
    "customerId": "cust_1a2b3c4d",
    "listingId": "listing_3m4n5o6p",
    "dimension": "api_calls",
    "quantity": 1000,
    "timestamp": "2026-01-16T12:00:00Z",
    "meteringRecordId": "mr-aws-abc123",
    "submittedAt": "2026-01-16T12:00:01Z"
  }
}

Analytics

Get Revenue Analytics

Get revenue analytics for your organization.

http

GET /api/v1/analytics/revenue

Required Scope: read:analytics

Query Parameters:

Parameter	Type	Description
`startDate`	string	Start date (ISO 8601)
`endDate`	string	End date (ISO 8601)
`vendor`	string	Filter by vendor: `aws`, `azure`
`listingId`	string	Filter by listing ID
`groupBy`	string	Group by: `day`, `week`, `month`, `year`

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/analytics/revenue?startDate=2026-01-01&endDate=2026-01-31&groupBy=week" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": {
    "total": 450000,
    "currency": "USD",
    "period": {
      "startDate": "2026-01-01",
      "endDate": "2026-01-31"
    },
    "breakdown": [
      {
        "period": "2026-01-01",
        "revenue": 95000,
        "contracts": 12
      },
      {
        "period": "2026-01-08",
        "revenue": 120000,
        "contracts": 15
      },
      {
        "period": "2026-01-15",
        "revenue": 115000,
        "contracts": 14
      },
      {
        "period": "2026-01-22",
        "revenue": 120000,
        "contracts": 16
      }
    ]
  }
}

Get Contract Statistics

Get contract statistics for your organization.

http

GET /api/v1/analytics/contracts

Required Scope: read:analytics

Query Parameters:

Parameter	Type	Description
`startDate`	string	Start date (ISO 8601)
`endDate`	string	End date (ISO 8601)
`vendor`	string	Filter by vendor: `aws`, `azure`
`status`	string	Filter by status: `active`, `expired`, `cancelled`

Example Request:

bash

curl -X GET "https://api.automatum.io/api/v1/analytics/contracts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Example Response:

json

{
  "code": 200,
  "data": {
    "total": 57,
    "active": 42,
    "expiringSoon": 5,
    "expired": 10,
    "byVendor": {
      "aws": 35,
      "azure": 22
    },
    "averageContractValue": 85000,
    "totalContractValue": 3570000
  }
}

Error Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or expired token
403	Forbidden	Insufficient permissions/scope
404	Not Found	Resource not found or not in your organization
409	Conflict	Resource conflict (e.g., duplicate)
422	Unprocessable Entity	Valid request but cannot be processed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
503	Service Unavailable	Service temporarily unavailable

Rate Limits

See Authentication Guide - Rate Limits for details.

Headers:

http

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1642334400

Pagination

All list endpoints support pagination:

Request:

http

GET /api/v1/customers?page=2&limit=50

Response:

json

{
  "code": 200,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 247,
    "pages": 5,
    "hasNext": true,
    "hasPrevious": true
  }
}

Filtering

Use query parameters to filter results:

http

GET /api/v1/private-offers?status=active&vendor=aws&listingId=listing_abc

Sorting

Sort results using the sort parameter:

http

GET /api/v1/customers?sort=-createdAt,companyName

Prefix with - for descending order
Multiple fields separated by commas

Idempotency

Use X-Idempotency-Key header to prevent duplicate operations:

bash

curl -X POST "https://api.automatum.io/api/v1/metering" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Next Steps

API Authentication - Learn about OAuth 2.0 authentication
Webhooks Setup - Set up real-time event notifications
API Integration Guide - Complete integration guide

API Reference ​

Base URL ​

Authentication ​

Response Format ​

Success Response ​

Error Response ​

Customers ​

List Customers ​

Get Customer ​

Entitlements ​

List Entitlements ​

Get Entitlement ​

Private Offers ​

List Private Offers ​

Get Private Offer ​

Metering ​

Submit Metering Data ​

Analytics ​

Get Revenue Analytics ​

Get Contract Statistics ​

Error Codes ​

Rate Limits ​

Pagination ​

Filtering ​

Sorting ​

Idempotency ​

Next Steps ​

API Reference

Base URL

Authentication

Response Format

Success Response

Error Response

Customers

List Customers

Get Customer

Entitlements

List Entitlements

Get Entitlement

Private Offers

List Private Offers

Get Private Offer

Metering

Submit Metering Data

Analytics

Get Revenue Analytics

Get Contract Statistics

Error Codes

Rate Limits

Pagination

Filtering

Sorting

Idempotency

Next Steps