Consuming Endpoints via the Data API

This guide walks through the full flow for consuming visualization endpoints via API key.

Overview

The flow has 3 steps:

1. Exchange api_key + api_secret for JWT tokens.
2. Execute the endpoint (sync or async).
3. Receive the result (immediately on sync, via polling on async).

Prerequisites

• An integration user with an active API key.
• The company_slug of the company.
• A visualization endpoint created and active (created via the console).
• data_api:execute permission assigned to the integration user.

Required Permissions

Endpoint	Minimum permission
POST /api/v1/data-api/:namespace/:slug/execute	data_api:execute
GET /api/v1/data-api/:namespace/:slug/jobs/:job_id	data_api:get_job

These permissions are included in the managed policies VisualizationViewer, VisualizationManager, and DataAPIConsumer.

To see the effective actions of the authenticated user, use GET /api/v1/auth/permissions.

Base URL by Environment

Environment	Base URL
Local	http://localhost:3100
Production	https://api.console.solucao42.com.br

export API_BASE_URL="http://localhost:3100"

Step 1: API Key Authentication

Use the API key only to obtain the JWT. Do not send the API key in subsequent calls.

curl -X POST "$API_BASE_URL/api/v1/auth/api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "api_key": "s42_xxxxxxxxx",
    "api_secret": "xxxxxxxxx"
  }'

Expected response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "access_token_expires_in": 600,
  "refresh_token_expires_in": 604800,
  "user": { ... }
}

Save the access_token for the following calls:

export TOKEN="eyJ..."

Step 2: Execute Endpoint (Sync)

For endpoints configured with execution_mode: sync:

curl -X POST "$API_BASE_URL/api/v1/data-api/default/vendas-por-regiao/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_values": {
      "data_inicio": "2026-01-01",
      "regiao": "Sul"
    }
  }'

Response (HTTP 200):

{
  "columns": [
    { "name": "regiao", "type": "varchar" },
    { "name": "total", "type": "decimal" }
  ],
  "rows": [
    { "regiao": "Sul", "total": 150000.00 }
  ],
  "row_count": 1,
  "truncated": false,
  "max_rows": 10000,
  "executed_at": "2026-04-11T10:30:00Z"
}

info

The sync execution timeout is 60 seconds. For longer queries, use endpoints in async mode.

Step 2 (alternative): Execute Endpoint (Async)

For endpoints configured with execution_mode: async:

curl -X POST "$API_BASE_URL/api/v1/data-api/default/relatorio-mensal/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "parameter_values": { "mes": "2026-03" },
    "callback_url": "https://my-system.com/webhook/result"
  }'

Response (HTTP 202):

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "processing",
  "polling_url": "/api/v1/data-api/default/relatorio-mensal/jobs/507f1f77bcf86cd799439011"
}

Step 3: Polling the Result (Async)

curl "$API_BASE_URL/api/v1/data-api/default/relatorio-mensal/jobs/507f1f77bcf86cd799439011" \
  -H "Authorization: Bearer $TOKEN"

While processing:

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "processing",
  "result": null,
  "error": null,
  "created_at": "2026-04-11T10:30:00Z",
  "completed_at": null
}

When complete:

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "completed",
  "result": {
    "columns": [...],
    "rows": [...],
    "row_count": 42,
    "truncated": false
  },
  "error": null,
  "created_at": "2026-04-11T10:30:00Z",
  "completed_at": "2026-04-11T10:30:45Z"
}

tip

If callback_url is provided, the system automatically POSTs to it when the job completes, removing the need to poll.

Error Handling

HTTP Status	Code	Cause
401	-	Missing or invalid token
403	FORBIDDEN	Missing data_api:execute or data_api:get_job permission
404	ENDPOINT_NOT_FOUND	Endpoint does not exist, is inactive, or belongs to another company
408	EXECUTION_TIMEOUT	Query exceeded the 60s timeout (use async mode)
422	-	Invalid parameter or value not allowed (share context)
500	INTERNAL_ERROR	Internal error during query execution

Token Refresh

The access_token expires in 10 minutes. To renew:

curl -X POST "$API_BASE_URL/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "eyJ..." }'