Skip to main content

​
Overview

The BR-ACC API is a Brazilian public data graph analysis tool built with FastAPI. It provides programmatic access to entity search, graph analysis, investigation tracking, and pattern detection across Brazilian public datasets. API Version: 0.1.0

​
Base URL

The API is typically deployed at: 
http://localhost:8000
All API endpoints are versioned and prefixed with /api/v1 (e.g., /api/v1/search).

​
Rate Limiting

The BR-ACC API implements rate limiting to ensure fair usage and system stability. Rate limits are applied per user (for authenticated requests) or per IP address (for anonymous requests).

​
Rate Limit Tiers

​
Anonymous requests
string
default:"60/minute"
Unauthenticated requests are limited to 60 requests per minute per IP address.
​
Authenticated requests
string
default:"300/minute"
Authenticated requests are limited to 300 requests per minute per user.

​
Endpoint-Specific Limits

Some endpoints have stricter rate limits:
  • Authentication endpoints (/api/v1/auth/register, /api/v1/auth/login): 10/minute
  • Search endpoints (/api/v1/search): 30/minute
  • Pattern detection endpoints (/api/v1/patterns/*): 30/minute

​
Rate Limit Response

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "Rate limit exceeded: 30 per 1 minute"
}

​
Rate Limit Headers

The API includes standard rate limit headers in responses:
  • X-RateLimit-Limit: The maximum number of requests allowed
  • X-RateLimit-Remaining: The number of requests remaining in the current window
  • X-RateLimit-Reset: The time when the rate limit resets (Unix timestamp)

​
Pagination

Many list endpoints support pagination using page and size query parameters.

​
Pagination Parameters

​
page
integer
default:"1"
Page number (1-indexed). Must be >= 1.
​
size
integer
default:"20"
Number of results per page. Must be between 1 and 100.

​
Pagination Response Format

Endpoints that support pagination return responses with the following structure: 
{
  "results": [...],
  "total": 150,
  "page": 1,
  "size": 20
}
​
results
array
Array of result objects for the current page.
​
total
integer
Total number of results available across all pages.
​
page
integer
Current page number.
​
size
integer
Number of results per page.

​
Example Paginated Request

curl -X GET "http://localhost:8000/api/v1/search?q=empresa&page=2&size=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Cursor-Based Pagination

Some endpoints (like entity events) use cursor-based pagination for efficient traversal of time-series data:
​
cursor
string
Cursor for the next page of results (returned in previous response).
​
limit
integer
default:"50"
Maximum number of results to return (1-100).
Cursor-based responses include a next_cursor field: 
{
  "events": [...],
  "next_cursor": "2024-01-15T10:30:00Z"
}
Pass the next_cursor value as the cursor parameter in the next request to continue pagination.

​
Health Check

The API provides a health check endpoint to verify service availability: 
curl http://localhost:8000/health
Response: 
{
  "status": "ok"
}

​
CORS Configuration

The API supports Cross-Origin Resource Sharing (CORS) with configurable allowed origins. By default, the API allows requests from http://localhost:3000. CORS is configured to allow:
  • Credentials (cookies, authorization headers)
  • All HTTP methods
  • All headers

​
Security Headers

The BR-ACC API implements security best practices including:
  • Security Headers Middleware: Adds security headers to all responses
  • CPF Masking Middleware: Automatically masks sensitive Brazilian CPF numbers in responses
  • HTTPS: Secure cookies are enforced in production environments

​
Error Handling

The API uses standard HTTP status codes:
  • 200 OK: Successful request
  • 201 Created: Resource successfully created
  • 204 No Content: Successful request with no response body
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid credentials
  • 403 Forbidden: Authenticated but insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., email already registered)
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error
Error responses include a detail field with a description: 
{
  "detail": "Invalid credentials"
}

​
Next Steps

Authentication

Learn how to register and authenticate users

Search Entities

Search for entities in the Brazilian public data graph

Build docs developers (and LLMs) love

Get started for freeTalk to us