Connect product usage
directly to atEaseAI.

WHEN TO USE THIS API

Understand adoption without
a product analytics tool.

Use this direct integration when you want to bring customer usage from your SaaS product into atEaseAI. Your development team configures your backend to send selected events; atEaseAI connects that activity to your customer accounts.

GETTING STARTED

Set up the account, access, and event mapping.

Start with a customer account you can identify reliably, then send a small test event from your backend.

1. Prepare your customer account

   Add the customer in atEaseAI and note its external ID, such as ACC-1. Use the lookup endpoint to verify the mapping.

2. Open Settings → API & Webhooks

   A workspace user with the API & Webhooks permission can view the API key and API Base URL. Ask your workspace administrator if this section is unavailable.

3. Configure your server environment

   Store the displayed API Base URL as ATEASE_API_BASE_URL and the key as ATEASE_API_KEY. The base URL shown in the app includes /api; append endpoint paths such as /usage/track.

4. Choose the events your team needs

   Start with a login event. For feature adoption, define the product feature catalog and retrieve feature IDs with GET /api/usage/features.

AUTHENTICATION

Use an organization API key.

For server-to-server usage integration, send your key as a Bearer token. The key identifies the organization and scopes account access to that organization.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

QUICK START

Send your first usage event.

Choose a server-side example. The sample sends a login event for an existing account and includes an event ID for safe retries.

# Set these in your server environment first:
# ATEASE_API_BASE_URL = API Base URL from Settings (includes /api)
# ATEASE_API_KEY = your organization API key

curl --request POST "$ATEASE_API_BASE_URL/usage/track" \
  --header "Authorization: Bearer $ATEASE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '
{
  "external_id": "ACC-1",
  "event_type": "login",
  "user_id": "user_123",
  "external_event_id": "login-event-0001",
  "event_source": "web_app"
}
'

// Node.js 18+ · Run on your server, not in the browser.
const baseUrl = process.env.ATEASE_API_BASE_URL.replace(/\/$/, '');
const response = await fetch(`${baseUrl}/usage/track`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ATEASE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "external_id": "ACC-1",
    "event_type": "login",
    "user_id": "user_123",
    "external_event_id": "login-event-0001",
    "event_source": "web_app"
}),
});
const result = await response.json();
if (!response.ok) throw new Error(JSON.stringify(result));
console.log(result);

# Server-side example · Requires the requests package.
import os
import requests

base_url = os.environ["ATEASE_API_BASE_URL"].rstrip("/")
response = requests.post(
    f"{base_url}/usage/track",
    headers={"Authorization": f"Bearer {os.environ['ATEASE_API_KEY']}"},
    json={
        "external_id": "ACC-1",
        "event_type": "login",
        "user_id": "user_123",
        "external_event_id": "login-event-0001",
        "event_source": "web_app"
},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Code examples are provided for your backend integration. Use a new external_event_id for each distinct event; reuse it when retrying the same event.

A successful response

{
  "success": true,
  "event_id": "8e392685-6cb6-436f-9536-0a91ed098b23",
  "message": "Usage event tracked successfully"
}

Accepted account events queue a health refresh. Ingestion success does not mean every derived metric or health view has refreshed immediately.

ENDPOINT REFERENCE

Four endpoints for usage integration.

Each endpoint below supports an organization API key. Full paths include /api; when using the base URL from Settings, append only the path after that prefix.

{
  "external_id": "ACC-1",
  "event_type": "login",
  "user_id": "user_123",
  "external_event_id": "login-event-0001",
  "event_source": "web_app"
}

{
  "success": true,
  "event_id": "8e392685-6cb6-436f-9536-0a91ed098b23",
  "message": "Usage event tracked successfully"
}

{
  "events": [
    {
      "external_id": "ACC-1",
      "event_type": "login",
      "user_id": "user_123",
      "external_event_id": "login-event-0001",
      "event_source": "web_app"
    },
    {
      "external_id": "ACC-1",
      "event_type": "feature_used",
      "user_id": "user_123",
      "external_event_id": "feature-event-0001",
      "metadata": {
        "feature_id": "YOUR_CATALOG_FEATURE_ID"
      }
    }
  ]
}

{
  "success": true,
  "tracked": 2,
  "skipped": 0,
  "duplicates": 0,
  "message": "Processed 2 events, skipped 0, 0 duplicate(s)"
}

GET /api/usage/accounts/lookup?external_id=ACC-1

{
  "account_id": "f1b730ce-8dfb-4cb7-a4b1-2011bcd54a80",
  "external_id": "ACC-1",
  "company_name": "AcmeCloud",
  "primary_contact_email": "alex@example.com",
  "message": "Use external_id in your usage tracking API calls (e.g., {'external_id': 'ACC-1', 'event_type': 'login'})"
}

GET /api/usage/features

{
  "features": [
    {
      "id": "788a7c12-b8eb-49d8-a5b4-959426139c03",
      "name": "Reports",
      "description": "Create and review reports",
      "product_id": "a77708a7-e0b3-4cf7-a98b-63f10db2b7bc",
      "product_name": "Example Product"
    }
  ],
  "total": 1
}

Examples show the endpoint-specific response fields. Replace example IDs, account details, and counts with your own values.

EVENT SCHEMA

Describe the activity and the customer.

The same event object is used for a single request and each item in a batch. Prefer a stable account identifier and a unique event ID from your own system.

Compatibility: event_data is accepted as a legacy alias for metadata. Prefer metadata in new integrations. Provider event ID aliases uuid, $insert_id, and insert_id are also recognized.

Choose useful event details.

DELIVERY & LIMITS

Deliver events with retries in mind.

Use stable event identifiers, inspect batch results, and keep traffic within the ingestion limits.

ERROR HANDLING

Check the status and response body.

Successful responses are endpoint-specific. Error payloads commonly include a detail field; validation errors may return a structured list of field issues.

{
  "detail": "Account not found"
}

COMMON QUESTIONS

A few details that help integrations work.