Listar dispositivos de una entidad

curl --request GET \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/devices/entity/{entityId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/devices/entity/{entityId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/devices/entity/{entityId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/devices/entity/{entityId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "devices": [
    {
      "devices[].id": "<string>",
      "devices[].deviceId": "<string>",
      "devices[].externalId": "<string>",
      "devices[].entityId": "<string>",
      "devices[].entityExternalId": "<string>",
      "devices[].entityTaxId": "<string>",
      "devices[].deviceName": "<string>",
      "devices[].deviceDetails": {},
      "devices[].platform": "<string>",
      "devices[].manufacturer": "<string>",
      "devices[].model": "<string>",
      "devices[].brand": "<string>",
      "devices[].osName": "<string>",
      "devices[].osVersion": "<string>",
      "devices[].browser": "<string>",
      "devices[].browserVersion": "<string>",
      "devices[].latitude": 123,
      "devices[].longitude": 123,
      "devices[].city": "<string>",
      "devices[].region": "<string>",
      "devices[].country": "<string>",
      "devices[].countryCode": "<string>",
      "devices[].ipAddress": "<string>",
      "devices[].isEmulator": true,
      "devices[].isRooted": true,
      "devices[].isBlocked": true,
      "devices[].isTrusted": true,
      "devices[].firstSeenAt": "<string>",
      "devices[].lastSeenAt": "<string>",
      "devices[].createdAt": "<string>",
      "devices[].updatedAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

GET

devices

entity

{entityId}

Listar dispositivos de una entidad

curl --request GET \
  --url http://api.gu1.ai/devices/entity/{entityId} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('http://api.gu1.ai/devices/entity/{entityId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/devices/entity/{entityId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/devices/entity/{entityId}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/devices/entity/{entityId}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "devices": [
    {
      "devices[].id": "<string>",
      "devices[].deviceId": "<string>",
      "devices[].externalId": "<string>",
      "devices[].entityId": "<string>",
      "devices[].entityExternalId": "<string>",
      "devices[].entityTaxId": "<string>",
      "devices[].deviceName": "<string>",
      "devices[].deviceDetails": {},
      "devices[].platform": "<string>",
      "devices[].manufacturer": "<string>",
      "devices[].model": "<string>",
      "devices[].brand": "<string>",
      "devices[].osName": "<string>",
      "devices[].osVersion": "<string>",
      "devices[].browser": "<string>",
      "devices[].browserVersion": "<string>",
      "devices[].latitude": 123,
      "devices[].longitude": 123,
      "devices[].city": "<string>",
      "devices[].region": "<string>",
      "devices[].country": "<string>",
      "devices[].countryCode": "<string>",
      "devices[].ipAddress": "<string>",
      "devices[].isEmulator": true,
      "devices[].isRooted": true,
      "devices[].isBlocked": true,
      "devices[].isTrusted": true,
      "devices[].firstSeenAt": "<string>",
      "devices[].lastSeenAt": "<string>",
      "devices[].createdAt": "<string>",
      "devices[].updatedAt": "<string>"
    }
  ],
  "pagination": {
    "pagination.total": 123,
    "pagination.limit": 123,
    "pagination.offset": 123,
    "pagination.hasMore": true
  }
}

Resumen

Recupera todos los dispositivos registrados para una entidad específica, ordenados por última actividad. Usa este endpoint para monitorear patrones de uso de dispositivos, detectar acceso sospechoso y construir reglas de detección de fraude basadas en dispositivos.

Endpoint

GET https://api.gu1.ai/devices/entity/{entityId}

Autenticación

Requiere una clave API válida en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Parámetros de Ruta

string

required

UUID de la entidad cuyos dispositivos deseas recuperar

Parámetros de Consulta

number

default:"50"

Número máximo de dispositivos a devolver por página (máx: 1000)Ejemplo: ?limit=100

number

default:"0"

Número de dispositivos a omitir para paginaciónEjemplo: ?offset=50

Contexto de investigación

Para obtener los dispositivos agrupados por la entidad investigada y, opcionalmente, por sus entidades relacionadas directas, usá:

GET /devices/entity/{entityId}/investigation-context?includeRelatedEntities=true

Cuando es true, incluye dispositivos de relaciones directas activas en ambas direcciones. Todas las entidades, relaciones y dispositivos quedan limitados a la organización autenticada.

La respuesta devuelve totalDevices y un array entities. Cada entidad incluye id, externalId, name, type, isPrimary, relationshipTypes y su array devices. Las entidades relacionadas sin dispositivos se omiten; la entidad principal siempre se devuelve.

Respuesta

boolean

Indica si la solicitud fue exitosa

array

Array de objetos de dispositivo ordenados por lastSeenAt (más reciente primero)

string

UUID interno del dispositivo de gu1

string

Identificador del dispositivo

string

Identificador externo del dispositivo

string

UUID de la entidad asociada

string

ID externo de la entidad (desnormalizado)

string

Tax ID de la entidad (desnormalizado)

string

Nombre del dispositivo definido por el usuario o nombre del hardware

object

Metadatos adicionales del dispositivo (objeto JSON). Detalles por plataforma.

string

Plataforma del dispositivo (android, ios, web)

string

Fabricante del dispositivo

string

Modelo del dispositivo

string

Marca del dispositivo

string

Nombre del sistema operativo

string

Versión del sistema operativo

string

Nombre del navegador (solo web)

string

Versión del navegador (solo web)

number

Latitud geográfica

number

Longitud geográfica

string

Nombre de la ciudad

string

Estado/provincia

string

Nombre del país

string

Código de país ISO

string

Última dirección IP conocida

boolean

Si el dispositivo es un emulador

boolean

Si el dispositivo está rooteado/jailbreakeado

boolean

Si el dispositivo está bloqueado

boolean

Si el dispositivo es confiable

string

Marca de tiempo de primera vez visto (ISO 8601)

string

Marca de tiempo de última vez visto (ISO 8601)

string

Marca de tiempo de creación

string

Marca de tiempo de última actualización

object

Información de paginación

number

Número total de dispositivos para esta entidad

number

Límite de tamaño de página usado

number

Desplazamiento usado

boolean

Si hay más páginas disponibles

Ejemplos

Consulta Básica

curl https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(data.devices);

import requests

response = requests.get(
    'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY'
    }
)

data = response.json()
print(data['devices'])

Con Paginación

curl "https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch(
  'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000?limit=20&offset=0',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);

const data = await response.json();
console.log(`Página 1 de ${Math.ceil(data.pagination.total / 20)} páginas`);

import requests

response = requests.get(
    'https://api.gu1.ai/devices/entity/550e8400-e29b-41d4-a716-446655440000',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'limit': 20, 'offset': 0}
)

data = response.json()
print(f"Página 1 de {data['pagination']['total'] // 20 + 1} páginas")

Ejemplo de Respuesta

{
  "success": true,
  "devices": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "deviceId": "840e89e4d46efd67",
      "externalId": "840e89e4d46efd67",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "entityTaxId": "20-12345678-9",
      "deviceName": "Galaxy A15",
      "deviceDetails": {},
      "platform": "android",
      "manufacturer": "samsung",
      "model": "SM-A156M",
      "brand": "samsung",
      "osName": "Android",
      "osVersion": "Android 16",
      "browser": null,
      "browserVersion": null,
      "latitude": -34.6037,
      "longitude": -58.3816,
      "city": "Buenos Aires",
      "region": "Buenos Aires",
      "country": "Argentina",
      "countryCode": "AR",
      "ipAddress": "10.40.64.231",
      "isEmulator": false,
      "isRooted": false,
      "isBlocked": false,
      "isTrusted": true,
      "firstSeenAt": "2026-01-20T10:00:00Z",
      "lastSeenAt": "2026-01-30T14:30:00Z",
      "createdAt": "2026-01-20T10:00:00Z",
      "updatedAt": "2026-01-30T14:30:00Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "deviceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityExternalId": "user_12345",
      "entityTaxId": null,
      "deviceName": null,
      "deviceDetails": {},
      "platform": "web",
      "manufacturer": null,
      "model": null,
      "brand": null,
      "osName": "Windows",
      "osVersion": null,
      "browser": "Chrome",
      "browserVersion": "120.0.6099.129",
      "latitude": -34.6037,
      "longitude": -58.3816,
      "city": "Buenos Aires",
      "region": "Buenos Aires",
      "country": "Argentina",
      "countryCode": "AR",
      "ipAddress": "10.40.64.231",
      "isEmulator": false,
      "isRooted": false,
      "isBlocked": false,
      "isTrusted": false,
      "firstSeenAt": "2026-01-25T08:15:00Z",
      "lastSeenAt": "2026-01-30T12:00:00Z",
      "createdAt": "2026-01-25T08:15:00Z",
      "updatedAt": "2026-01-30T12:00:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

Respuestas de Error

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions to read devices"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "DEVICES_FETCH_FAILED",
    "message": "Failed to fetch entity devices"
  }
}

Casos de Uso

Panel de Inventario de Dispositivos

Construye un panel mostrando todos los dispositivos usados por tus entidades:

async function getDeviceInventory(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Agrupar por plataforma
  const byPlatform = data.devices.reduce((acc, device) => {
    acc[device.platform] = (acc[device.platform] || 0) + 1;
    return acc;
  }, {});

  console.log('Dispositivos por plataforma:', byPlatform);
  return data.devices;
}

Detección de Fraude

Detecta patrones de dispositivos sospechosos:

async function detectSuspiciousDevices(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Marcar dispositivos sospechosos
  const suspicious = data.devices.filter(device =>
    device.isEmulator ||
    device.isRooted ||
    device.isBlocked
  );

  if (suspicious.length > 0) {
    console.warn('Dispositivos sospechosos encontrados:', suspicious);
  }

  return suspicious;
}

Análisis Geográfico

Analiza ubicaciones de dispositivos para anomalías:

async function analyzeDeviceLocations(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();

  // Obtener países únicos
  const countries = new Set(
    data.devices.map(d => d.countryCode).filter(Boolean)
  );

  // Marcar si hay dispositivos de múltiples países
  if (countries.size > 1) {
    console.warn('Dispositivos desde múltiples países:', Array.from(countries));
  }

  return Array.from(countries);
}

Monitoreo de Actividad

Monitorea actividad reciente de dispositivos:

async function getRecentDevices(entityId, hours = 24) {
  const response = await fetch(
    `https://api.gu1.ai/devices/entity/${entityId}`,
    {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    }
  );

  const data = await response.json();
  const cutoff = new Date(Date.now() - hours * 60 * 60 * 1000);

  // Filtrar dispositivos activos en las últimas N horas
  const recentDevices = data.devices.filter(device =>
    new Date(device.lastSeenAt) > cutoff
  );

  console.log(`${recentDevices.length} dispositivos activos en las últimas ${hours} horas`);
  return recentDevices;
}

Mejores Prácticas de Paginación

Iterar a Través de Todas las Páginas

async function getAllDevices(entityId) {
  const allDevices = [];
  let offset = 0;
  const limit = 100;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://api.gu1.ai/devices/entity/${entityId}?limit=${limit}&offset=${offset}`,
      {
        headers: { 'Authorization': `Bearer ${API_KEY}` }
      }
    );

    const data = await response.json();
    allDevices.push(...data.devices);

    hasMore = data.pagination.hasMore;
    offset += limit;
  }

  console.log(`Total de dispositivos: ${allDevices.length}`);
  return allDevices;
}

Próximos Pasos

Crear Dispositivo

Registrar un nuevo dispositivo

API de Eventos

Aprende sobre registro automático de dispositivos

Detección de Fraude

Construye reglas de fraude basadas en dispositivos

Matriz de Riesgo

Configura puntuación de riesgo con datos de dispositivos

​Resumen

​Endpoint

​Autenticación

​Parámetros de Ruta

​Parámetros de Consulta

​Contexto de investigación

​Respuesta

​Ejemplos

​Consulta Básica

​Con Paginación

​Ejemplo de Respuesta

​Respuestas de Error

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Panel de Inventario de Dispositivos

​Detección de Fraude

​Análisis Geográfico

​Monitoreo de Actividad

​Mejores Prácticas de Paginación

​Iterar a Través de Todas las Páginas

​Próximos Pasos

Crear Dispositivo

API de Eventos

Detección de Fraude

Matriz de Riesgo

Resumen

Endpoint

Autenticación

Parámetros de Ruta

Parámetros de Consulta

Contexto de investigación

Respuesta

Ejemplos

Consulta Básica

Con Paginación

Ejemplo de Respuesta

Respuestas de Error

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Panel de Inventario de Dispositivos

Detección de Fraude

Análisis Geográfico

Monitoreo de Actividad

Mejores Prácticas de Paginación

Iterar a Través de Todas las Páginas

Próximos Pasos