Using Postman

Postman lets you test Datafala's HTTP calls before integrating the API into your system. You can import the endpoints described in this documentation and configure an API key for the authenticated requests.

Import the endpoints

The Datafala OpenAPI contract is available at:

https://datafala.com.br/openapi/swagger.json

In Postman:

1. Select Import.
2. Choose to import by Link.
3. Enter the OpenAPI URL above and confirm.
4. Save the generated collection.

The contract includes only the endpoints described in the API reference, and it can be updated together with the documentation.

Configure variables

Create an Environment in Postman with these variables:

Variable	Initial value	Use
baseUrl	https://app.datafala.com.br	Base URL of the API.
apiKey	your tsk_... key	Tenant key, marked as secret/sensitive in Postman.
endUser	stable opaque identifier	Used in the /v1/ask body when the tenant requires it.

In the collection requests, set the URL as {{baseUrl}} followed by the endpoint path. In the /v1/* calls, send the header:

Authorization: Bearer {{apiKey}}

Do not share or version the API key value. It is shown only once when created and must be kept protected as a secret.

Ask a question

Use POST {{baseUrl}}/v1/ask, select Body → raw → JSON and send:

{
  "question": "How many orders were placed yesterday?",
  "end_user": "{{endUser}}",
  "max_rows": 100,
  "locale": "en"
}

The end_user field is required for tenants that require it. See the end-user identifier guide to generate a stable opaque value; do not send a name, email or other personal data.

A successful response contains the validated SQL, the named parameters, the tables used and a request_id. Datafala does not run the SQL or access the customer's database: run the query in your backend with the appropriate permissions.

Query history and send feedback

All the operations below use Authorization: Bearer {{apiKey}}:

Method	URL	Description
GET	{{baseUrl}}/v1/history?limit=10	Lists recent answers.
GET	{{baseUrl}}/v1/history/{{requestId}}	Fetches an answer by its request_id.
POST	{{baseUrl}}/v1/feedback	Sends a rating for an answer.

To send feedback, add requestId as a variable and use a JSON body:

{
  "request_id": "{{requestId}}",
  "rating": "good"
}

rating accepts good or bad; the optional comment can be sent in the comment field. The success response is 204 No Content.

Check the health of the service

The health endpoints do not require an API key:

GET {{baseUrl}}/healthz
GET {{baseUrl}}/readyz

/healthz checks whether the process is active. /readyz checks whether the API can reach its own database.

Common errors

• 401 invalid_api_key: check that the API key is correct, active and sent as a Bearer token.
• 400 end_user_required: send a stable end_user identifier.
• 409 schema_not_configured or llm_not_configured: the tenant administrator needs to finish the configuration in the panel.
• 422 no_answer or sql_rejected: rephrase the question according to the data registered in the schema.
• 429 rate_limited: wait for the period shown in the Retry-After header before repeating.
• 502 llm_error: check the LLM provider's configuration or availability.

See the full list in the Error reference. For POST /v1/ask calls, set a timeout of at least 60 seconds and do not automatically repeat a request that timed out.