Skip to main content
GET
/
api
/
v1
/
search
Search Entities
curl --request GET \
  --url https://api.example.com/api/v1/search
{
  "results": [
    {
      "id": "<string>",
      "type": "<string>",
      "name": "<string>",
      "score": 123,
      "document": "<string>",
      "properties": {},
      "sources": [
        {
          "database": "<string>",
          "record_id": "<string>",
          "extracted_at": "<string>"
        }
      ],
      "exposure_tier": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "size": 123
}
Search for entities across the BR-ACC knowledge graph using full-text search with Lucene query syntax.

​
Authentication

This endpoint supports optional authentication via:
  • Bearer token: Include Authorization: Bearer <token> header
  • Session cookie: Automatically sent by browser after login
Unauthenticated requests are rate-limited to 30 requests per minute per IP address. Authenticated requests use per-user rate limiting.

​
Query Parameters

​
q
string
required
Search query string. Minimum 2 characters, maximum 200 characters. Special Lucene characters are automatically escaped for safety.
​
type
string
Filter results by entity type. Available types:
  • person - Individual persons
  • company - Companies and organizations
  • contract - Government contracts
  • amendment - Contract amendments
  • sanction - Administrative sanctions
  • embargo - Environmental embargoes
  • convenio - Federal agreements
  • election - Electoral data
  • finance - Financial records
  • health - Healthcare facilities
  • education - Educational institutions
  • laborstats - Labor statistics
​
page
integer
default:"1"
Page number for pagination (minimum: 1)
​
size
integer
default:"20"
Number of results per page (minimum: 1, maximum: 100)

​
Response

​
results
array
Array of matching entities
​
id
string
Unique element ID for the entity in Neo4j graph database
​
type
string
Entity type (e.g., “person”, “company”, “contract”)
​
name
string
Display name extracted based on entity type:
  • Company: razao_social or nome_fantasia
  • Contract/Amendment: object or function description
  • Embargo: infraction description
  • Other types: name property
​
score
float
Search relevance score (higher is more relevant)
​
document
string
Primary document identifier (CPF/CNPJ) if available. Internal element IDs are excluded for privacy.
​
properties
object
Key-value pairs of entity properties. Sensitive fields are sanitized before exposure.
​
sources
array
Data provenance information
​
database
string
Source database name
​
record_id
string
Original record identifier in source system
​
extracted_at
string
ISO 8601 timestamp of data extraction
​
exposure_tier
string
default:"public_safe"
Data sensitivity classification (e.g., “public_safe”, “restricted”)
​
total
integer
Total number of matching entities across all pages
​
page
integer
Current page number
​
size
integer
Number of results per page

​
Example Request

curl -X GET "https://api.br-acc.com/api/v1/search?q=petrobras&type=company&page=1&size=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "results": [
    {
      "id": "4:abc123:1",
      "type": "company",
      "name": "Petróleo Brasileiro S.A.",
      "score": 9.87,
      "document": "33000167000101",
      "properties": {
        "razao_social": "Petróleo Brasileiro S.A.",
        "nome_fantasia": "Petrobras",
        "cnpj": "33.000.167/0001-01",
        "uf": "RJ"
      },
      "sources": [
        {
          "database": "receita_federal"
        }
      ],
      "exposure_tier": "public_safe"
    }
  ],
  "total": 42,
  "page": 1,
  "size": 10
}

​
Privacy Controls

When the HIDE_PERSON_ENTITIES environment variable is enabled:
  • Person entities are automatically filtered from search results
  • Only non-person entity types are returned
  • This protects individual privacy in public deployments

​
Rate Limiting

  • Limit: 30 requests per minute
  • Key: User ID (authenticated) or IP address (anonymous)
  • Response: HTTP 429 when limit exceeded

​
Implementation Details

From search.py:44-114:
  • Uses Neo4j full-text index for fast searching
  • Automatically escapes Lucene special characters in queries
  • Supports pagination with configurable page size
  • Sanitizes properties before public exposure
  • Filters internal element IDs from document field

Build docs developers (and LLMs) love

Get started for freeTalk to us