Listar dispositivos de uma entidade

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 uma entidade

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
  }
}

Visão Geral

Recupera todos os dispositivos registrados para uma entidade específica, ordenados por última atividade. Use este endpoint para monitorar padrões de uso de dispositivos, detectar acessos suspeitos e construir regras de detecção de fraude baseadas em dispositivos.

Endpoint

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

Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Parâmetros de Caminho

string

required

UUID da entidade cujos dispositivos você deseja recuperar

Parâmetros de Consulta

number

default:"50"

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

number

default:"0"

Número de dispositivos a pular para paginaçãoExemplo: ?offset=50

Contexto de investigação

Para obter os dispositivos agrupados pela entidade investigada e, opcionalmente, por suas entidades relacionadas diretas, use:

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

Quando true, inclui dispositivos de relações diretas ativas em ambas as direções. Todas as entidades, relações e dispositivos permanecem limitados à organização autenticada.

A resposta retorna totalDevices e um array entities. Cada entidade inclui id, externalId, name, type, isPrimary, relationshipTypes e seu array devices. Entidades relacionadas sem dispositivos são omitidas; a entidade principal sempre é retornada.

Resposta

boolean

Indica se a requisição foi bem-sucedida

array

Array de objetos de dispositivos ordenados por lastSeenAt (mais recente primeiro)

string

UUID interno do dispositivo no gu1

string

Identificador do dispositivo

string

Identificador externo do dispositivo

string

UUID da entidade associada

string

ID externo da entidade (desnormalizado)

string

Tax ID da entidade (desnormalizado)

string

Nome do dispositivo definido pelo usuário ou nome do hardware

object

Metadados adicionais do dispositivo (objeto JSON). Detalhes por plataforma.

string

Plataforma do dispositivo (android, ios, web)

string

Fabricante do dispositivo

string

Modelo do dispositivo

string

Marca do dispositivo

string

Nome do sistema operacional

string

Versão do sistema operacional

string

Nome do navegador (somente web)

string

Versão do navegador (somente web)

number

Latitude geográfica

number

Longitude geográfica

string

Nome da cidade

string

Estado/província

string

Nome do país

string

Código do país ISO

string

Último endereço IP conhecido

boolean

Se o dispositivo é um emulador

boolean

Se o dispositivo tem root/jailbreak

boolean

Se o dispositivo está bloqueado

boolean

Se o dispositivo é confiável

string

Timestamp da primeira vez visto (ISO 8601)

string

Timestamp da última vez visto (ISO 8601)

string

Timestamp de criação

string

Timestamp da última atualização

object

Informações de paginação

number

Número total de dispositivos desta entidade

number

Limite de tamanho de página usado

number

Offset usado

boolean

Se há mais páginas disponíveis

Exemplos

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'])

Com Paginação

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(`Page 1 of ${Math.ceil(data.pagination.total / 20)} pages`);

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"Page 1 of {data['pagination']['total'] // 20 + 1} pages")

Exemplo de Resposta

{
  "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
  }
}

Respostas de Erro

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

Dashboard de Inventário de Dispositivos

Construa um dashboard mostrando todos os dispositivos usados por suas 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('Devices by platform:', byPlatform);
  return data.devices;
}

Detecção de Fraude

Detecte padrões suspeitos de dispositivos:

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();

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

  if (suspicious.length > 0) {
    console.warn('Found suspicious devices:', suspicious);
  }

  return suspicious;
}

Análise Geográfica

Analise localizações de dispositivos para anomalias:

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();

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

  // Sinalizar se dispositivos de múltiplos países
  if (countries.size > 1) {
    console.warn('Devices from multiple countries:', Array.from(countries));
  }

  return Array.from(countries);
}

Monitoramento de Atividade

Monitore atividade recente 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 ativos nas últimas N horas
  const recentDevices = data.devices.filter(device =>
    new Date(device.lastSeenAt) > cutoff
  );

  console.log(`${recentDevices.length} devices active in last ${hours} hours`);
  return recentDevices;
}

Melhores Práticas de Paginação

Iterar Através de Todas as 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 devices: ${allDevices.length}`);
  return allDevices;
}

Próximos Passos

Criar Dispositivo

Registrar um novo dispositivo

API de Eventos

Aprenda sobre registro automático de dispositivos

Detecção de Fraude

Construa regras de fraude baseadas em dispositivos

Matriz de Risco

Configure pontuação de risco com dados de dispositivos

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Parâmetros de Consulta

​Contexto de investigação

​Resposta

​Exemplos

​Consulta Básica

​Com Paginação

​Exemplo de Resposta

​Respostas de Erro

​401 Unauthorized

​403 Forbidden

​404 Not Found

​500 Internal Server Error

​Casos de Uso

​Dashboard de Inventário de Dispositivos

​Detecção de Fraude

​Análise Geográfica

​Monitoramento de Atividade

​Melhores Práticas de Paginação

​Iterar Através de Todas as Páginas

​Próximos Passos

Criar Dispositivo

API de Eventos

Detecção de Fraude

Matriz de Risco

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Parâmetros de Consulta

Contexto de investigação

Resposta

Exemplos

Consulta Básica

Com Paginação

Exemplo de Resposta

Respostas de Erro

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

Casos de Uso

Dashboard de Inventário de Dispositivos

Detecção de Fraude

Análise Geográfica

Monitoramento de Atividade

Melhores Práticas de Paginação

Iterar Através de Todas as Páginas

Próximos Passos