counters`

Endpoint: GET /api/v1/daemonx/counters
Auth Scope: Developer Token Protected (Authorization: Bearer nyx_daemonx_live_...)
Target Service: Nyxzie Cloud Core API
Introduced In: v1.0.0
Last Updated: v1.0.0

1. Description & Purpose

GET /api/v1/daemonx/counters is a B2B developer management endpoint that enables external platforms, POS frontends, and SaaS backends to query and inspect all retail counters associated with their DaemonX developer profile.

Key features:

Multi-Store & Tenant Filtering: Query by your platform's own external references (external_customer_ref, external_location_ref, external_counter_ref).
Liveness & State Peeking: Inspect whether the counter is currently registered (is_active), connected to the cloud (is_online), and its cumulative lifetime print jobs (total_jobs_completed).
Privacy & Sanitization: Internal infrastructure timestamps (such as low-level worker heartbeats) are stripped from this public B2B DTO.

2. Request Headers

Header Name	Type	Required	Description	Example
`Authorization`	`string`	Yes	Developer API Bearer Token	`Bearer nyx_daemonx_live_6b431eda073e...`
`Accept`	`string`	No	Response format	`application/json`

3. Query Parameters

All query parameters are optional, trimmed strings (1–255 characters):

Parameter	Type	Required	Description	Example
`external_customer_ref`	`string`	Optional	Filter by merchant/customer identifier in your external platform.	`cust_milan_01`
`external_location_ref`	`string`	Optional	Filter by store branch or physical venue identifier.	`loc_colombo_flagship`
`external_counter_ref`	`string`	Optional	Filter by specific register / workstation identifier.	`pos_lane_01`

4. TypeScript Contracts

export interface DaemonxCounterListItem {
  counter_id: string;
  counter_name: string;
  environment: 'live' | 'sandbox';
  external_customer_ref?: string;
  external_location_ref?: string;
  external_counter_ref?: string;
  is_active: boolean;
  is_online: boolean;
  total_jobs_completed: number;
  created_at: string;
}

export interface DaemonxCounterListResponse {
  success: true;
  counters: DaemonxCounterListItem[];
}

export interface DaemonxErrorResponse {
  success: false;
  error: string;
  code?: string;
}

5. Successful Response (200 OK)

{
  "success": true,
  "counters": [
    {
      "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
      "counter_name": "Cashier Counter 1",
      "environment": "live",
      "external_customer_ref": "cust_milan_01",
      "external_location_ref": "loc_colombo_flagship",
      "external_counter_ref": "pos_lane_01",
      "is_active": true,
      "is_online": true,
      "total_jobs_completed": 1420,
      "created_at": "2026-09-24T18:42:10.000Z"
    },
    {
      "counter_id": "8f3b610c-99d1-4cb5-8271-9f26038101ee",
      "counter_name": "Bar Station Register",
      "environment": "live",
      "external_customer_ref": "cust_milan_01",
      "external_location_ref": "loc_colombo_flagship",
      "external_counter_ref": "pos_bar_02",
      "is_active": true,
      "is_online": false,
      "total_jobs_completed": 350,
      "created_at": "2026-09-28T11:15:33.000Z"
    }
  ]
}

6. Error Responses

401 Unauthorized

Returned when Authorization header is missing, malformed, or the API token is revoked.

{
  "success": false,
  "error": "Missing or invalid DaemonX API token.",
  "code": "UNAUTHORIZED"
}

429 Too Many Requests

Returned if request limits exceed the rate shield threshold.

{
  "success": false,
  "error": "Rate limit exceeded. Please throttle your requests.",
  "code": "RATE_LIMIT_EXCEEDED"
}

7. Integration Snippets

cURL

curl -X GET "https://api.nyxzie.com/api/v1/daemonx/counters?external_location_ref=loc_colombo_flagship" \
  -H "Authorization: Bearer nyx_daemonx_live_6b431eda073e6cb462bd0a9971687376ef5481887c46dfa688bcb618982fc905" \
  -H "Accept: application/json"

TypeScript Client Function

import type { DaemonxCounterListResponse, DaemonxCounterListItem } from './types';

export async function fetchDaemonxCounters(
  apiToken: string,
  filters?: {
    externalCustomerRef?: string;
    externalLocationRef?: string;
    externalCounterRef?: string;
  }
): Promise<DaemonxCounterListItem[]> {
  const url = new URL('https://api.nyxzie.com/api/v1/daemonx/counters');

  if (filters?.externalCustomerRef) {
    url.searchParams.set('external_customer_ref', filters.externalCustomerRef.trim());
  }
  if (filters?.externalLocationRef) {
    url.searchParams.set('external_location_ref', filters.externalLocationRef.trim());
  }
  if (filters?.externalCounterRef) {
    url.searchParams.set('external_counter_ref', filters.externalCounterRef.trim());
  }

  const res = await fetch(url.toString(), {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken.trim()}`,
      'Accept': 'application/json',
    },
  });

  if (!res.ok) {
    const errorBody = await res.json().catch(() => null);
    throw new Error(errorBody?.error || `Failed to fetch counters (HTTP ${res.status})`);
  }

  const data = (await res.json()) as DaemonxCounterListResponse;
  return data.counters;
}

List Counters