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
`limit`	integer	Items per page (default: 20, max: 100)
`cursor`	string	Opaque cursor for the next page (from `nextCursor`)

Example Request:

bash

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

Example Response:

json

{
  "code": 200,
  "data": {
    "items": [
      {
        "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"
      }
    ],
    "nextCursor": "eyJpZCI6ImN1c3RfMWEyYjNjNGQifQ"
  }
}

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
`limit`	integer	Items per page (default: 20, max: 100)
`cursor`	string	Opaque cursor for the next page (from `nextCursor`)

Example Request:

bash

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

Example Response:

json

{
  "code": 200,
  "data": {
    "items": [
      {
        "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"
      }
    ],
    "nextCursor": "eyJpZCI6ImVudF85aTBqMWsybCJ9"
  }
}

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
`limit`	integer	Items per page (default: 20, max: 100)
`cursor`	string	Opaque cursor for the next page (from `nextCursor`)

Example Request:

bash

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

Example Response:

json

{
  "code": 200,
  "data": {
    "items": [
      {
        "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"
      }
    ],
    "nextCursor": "eyJpZCI6Im9mZmVyXzdxOHI5czB0In0"
  }
}

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:

The metering payload uses a nested structure. The customer is identified under details.customer.id.

Field	Type	Required	Description
`details.customer.id`	string	Yes	Customer ID
`listingId`	string	No	Listing ID
`details.reportingDate`	string	No	ISO 8601 reporting date for the usage

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 '{
    "listingId": "listing_3m4n5o6p",
    "details": {
      "customer": {
        "id": "cust_1a2b3c4d"
      },
      "reportingDate": "2026-01-16T12:00:00Z"
    }
  }'

Example Response:

Returns HTTP 201 Created on success.

json

{
  "code": 201,
  "data": {
    "id": "meter_1u2v3w4x",
    "status": "accepted",
    "message": "Metering data submitted successfully"
  }
}

Analytics

Get Revenue Analytics

http

GET /api/v1/analytics/revenue

Required Scope: read:analytics

Not Yet Implemented

Revenue analytics is not yet available. The endpoint is reserved but its implementation is pending, so it currently returns a placeholder response rather than revenue data:

json

{
  "message": "Revenue analytics endpoint - implementation pending"
}

This endpoint and its response schema are coming soon. Do not build against it yet.

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": {
    "newContracts": 8,
    "totalContracts": 57,
    "expiringContracts": 5
  }
}

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 use cursor-based pagination. Pass a limit and, to fetch the next page, the cursor value returned as nextCursor in the previous response. When nextCursor is null, there are no more results.

Request:

http

GET /api/v1/customers?limit=50&cursor=eyJpZCI6ImN1c3RfMWEyYjNjNGQifQ

Response:

json

{
  "code": 200,
  "data": {
    "items": [],
    "nextCursor": "eyJpZCI6ImN1c3RfOXo4eTd4NncifQ"
  }
}

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 ​

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

Idempotency

Next Steps