Get Entity Graph

GET /api/v1/graph/{entity_id}

Get Entity Graph

cURL

curl --request GET \
  --url https://api.example.com/api/v1/graph/{entity_id}

200

{
  "nodes": [
    {
      "id": "<string>",
      "label": "<string>",
      "type": "<string>",
      "document_id": "<string>",
      "properties": {},
      "sources": [
        {}
      ],
      "is_pep": true,
      "exposure_tier": "<string>"
    }
  ],
  "edges": [
    {
      "id": "<string>",
      "source": "<string>",
      "target": "<string>",
      "type": "<string>",
      "properties": {},
      "confidence": 123,
      "sources": [
        {}
      ],
      "exposure_tier": "<string>"
    }
  ],
  "center_id": "<string>"
}

Retrieve a subgraph centered on a specific entity, including connected nodes and relationships up to a specified depth.

Authentication

This endpoint requires authentication via:

• Bearer token: Include Authorization: Bearer <token> header
• Session cookie: Automatically sent by browser after login

Entity lookup must be enabled via the ENTITY_LOOKUP_ENABLED configuration.

Path Parameters

entity_id · string · required

Neo4j element ID of the center entity (e.g., 4:abc123:1)

Query Parameters

depth · integer · default: "2"

Graph traversal depth (minimum: 1, maximum: 4)

Performance note: Depth is automatically capped at 1 for “supernodes” (entities with >500 connections) to prevent graph explosion.

entity_types · string

Comma-separated list of entity types to include in the graph. When specified, only these types and their relationships are returned.

Available types:

• person
• company
• contract
• sanction
• election
• amendment
• finance
• embargo
• health
• education
• convenio
• laborstats

Example: entity_types=company,person

Response

nodes · array

Array of graph nodes

id · string

Unique Neo4j element ID

label · string

Display label extracted from node properties:

• Company: razao_social or nome_fantasia
• Finance: “Finance: R$ ” or transaction type
• Embargo: description or state (UF)
• Convenio: object or convenio_id
• Other: name or id property

type · string

Entity type in lowercase

document_id · string

Primary identifier for the entity (CPF, CNPJ, contract_id, etc.)

properties · object

Slim property set optimized for graph rendering. Includes only essential fields:

• name, razao_social, cnpj, cpf
• value, date, type
• uf, cargo, partido

sources · array

Data provenance information

is_pep · boolean

Politically Exposed Person flag

exposure_tier · string

Data sensitivity classification

edges · array

Array of relationships between nodes

id · string

Unique Neo4j relationship element ID

source · string

Element ID of source node

target · string

Element ID of target node

type · string

Relationship type (e.g., “HAS_PARTNER”, “WON_CONTRACT”, “SANCTIONED”)

properties · object

Relationship properties (e.g., role, start_date, percentage)

confidence · float · default: "1.0"

Relationship confidence score (0.0 to 1.0)

sources · array

Data provenance for the relationship

exposure_tier · string

Always “public_safe” for relationships

center_id · string

Element ID of the center entity (same as path parameter)

Example Request

curl -X GET "https://api.br-acc.com/api/v1/graph/4:abc123:1?depth=2&entity_types=company,person" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "nodes": [
    {
      "id": "4:abc123:1",
      "label": "Acme Construções LTDA",
      "type": "company",
      "document_id": "12345678000100",
      "properties": {
        "razao_social": "Acme Construções LTDA",
        "cnpj": "12.345.678/0001-00",
        "uf": "SP"
      },
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "is_pep": false,
      "exposure_tier": "public_safe"
    },
    {
      "id": "4:def456:2",
      "label": "João Silva",
      "type": "person",
      "document_id": "12345678900",
      "properties": {
        "name": "João Silva",
        "cpf": "123.456.789-00"
      },
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "is_pep": false,
      "exposure_tier": "public_safe"
    }
  ],
  "edges": [
    {
      "id": "5:rel123:1",
      "source": "4:def456:2",
      "target": "4:abc123:1",
      "type": "HAS_PARTNER",
      "properties": {
        "role": "Sócio Administrador",
        "start_date": "2020-01-15"
      },
      "confidence": 1.0,
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "exposure_tier": "public_safe"
    }
  ],
  "center_id": "4:abc123:1"
}

Performance Optimizations

Supernode Detection

From graph.py:108-120:

Before graph expansion, the endpoint checks node degree:

• If degree > 500, entity is classified as a “supernode”
• Depth is automatically capped at 1 to prevent performance issues
• Prevents graph explosion for highly connected entities

Property Slimming

From graph.py:69-71:

Only essential properties are included in graph responses:

• Reduces payload size for large graphs
• Improves rendering performance in UI
• Use the /entity/{entity_id} endpoint for full property details

Label Filtering

From graph.py:74-94:

Internal system labels are automatically excluded:

• -User - Application users
• -Investigation - Investigation metadata
• -Annotation - User annotations
• -Tag - Custom tags

This ensures only domain entities appear in the graph.

Privacy Controls

When the HIDE_PERSON_ENTITIES environment variable is enabled:

• Person nodes are filtered from graph results
• Exception: Center entity can be a person if directly requested
• Edges connecting to removed nodes are also excluded
• This protects individual privacy in public deployments

Error Responses

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Person entity access denied (when center entity is a person and HIDE_PERSON_ENTITIES is enabled)

404 Not Found

Entity not found or has no connections

504 Gateway Timeout

Graph query exceeded 5-second timeout (typically for very large subgraphs)

Implementation Details

From graph.py:97-222:

• Uses APOC subgraphAll for efficient graph expansion
• Applies label filtering to exclude internal system nodes
• Deduplicates nodes and edges in response
• Enforces person access policies on center entity
• Extracts document IDs from multiple property fields
• Sanitizes properties before public exposure
• Includes 5-second query timeout for safety

Use Cases

1. Risk Analysis: Visualize connections between companies, contracts, and sanctions
2. Ownership Structures: Map company partnerships and shareholding relationships
3. Public Contract Networks: Trace government spending through contractors and amendments
4. PEP Screening: Identify politically exposed persons in business networks
5. Investigation Support: Explore entity relationships for due diligence