Data API

Endpoints for external consumption of visualizations via API key.

Execute Endpoint

POST/api/v1/data-api/:namespace/:slug/execute

Executes a visualization endpoint. The execution mode (sync or async) is set in the endpoint configuration.

Permission: data_api:execute

Path Parameters

Field	Type	Description
namespace	string	Endpoint namespace (kebab-case)
slug	string	Endpoint slug (kebab-case)

Body (optional)

Field	Type	Required	Description
parameter_values	object	No	Values for the visualization parameters
callback_url	string	No	Webhook URL for the result (async mode only, HTTPS required)

Sync Response (200)

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

Async Response (202)

{
  "job_id": "507f1f77bcf86cd799439011",
  "status": "processing",
  "polling_url": "/api/v1/data-api/:namespace/:slug/jobs/507f1f77bcf86cd799439011"
}

---

Get Job

GET/api/v1/data-api/:namespace/:slug/jobs/:job_id

Returns the status of an async execution job.

Permission: data_api:get_job

Path Parameters

Field	Type	Description
namespace	string	Endpoint namespace
slug	string	Endpoint slug
job_id	string	Job ID returned by the async execution

Response (200)

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

When status is completed, the result field contains:

{
  "columns": [{ "name": "string", "type": "string" }],
  "rows": [{}],
  "row_count": 0,
  "truncated": false
}

When status is failed, the error field contains the error message.

---

Error Codes

HTTP	Code	Description
400	INVALID_PARAMS	Missing namespace or slug
401	-	Missing or invalid token
403	FORBIDDEN	Missing required permission
404	ENDPOINT_NOT_FOUND	Endpoint does not exist, is inactive, or belongs to another company
404	JOB_NOT_FOUND	Job does not exist or does not belong to the endpoint
408	EXECUTION_TIMEOUT	Sync execution timed out (60s)
422	-	Invalid parameter or share-context violation
500	EXECUTION_ERROR	Query execution error
500	INTERNAL_ERROR	Internal error