# `GET /api/v1/daemonx/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:
1. **Multi-Store & Tenant Filtering:** Query by your platform's own external references (`external_customer_ref`, `external_location_ref`, `external_counter_ref`).
2. **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`).
3. **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

```typescript
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)

```json
{
  "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.
```json
{
  "success": false,
  "error": "Missing or invalid DaemonX API token.",
  "code": "UNAUTHORIZED"
}
```

### 429 Too Many Requests
Returned if request limits exceed the rate shield threshold.
```json
{
  "success": false,
  "error": "Rate limit exceeded. Please throttle your requests.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

---

## 7. Integration Snippets

### cURL
```bash
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
```typescript
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;
}
```