PersivX Data API

The Data API lets applications fetch data from any data source connected to PersivX. Be it an external relational database, a data lake or imported data in PersivX, the Data API provides a standard endpoint for fetching data in the desired format.

Steps:

Step 1: Authentication using OAuth 2.0
Step 2: Consuming data using Data API.

---

🔐 Authentication

All Data API endpoints require authentication with OAuth 2.0. Applications must obtain a valid access token and include it in the request header for authentication.

Authentication using OAuth 2.0

Endpoint:

POST https://app.persivx.com/api/o/token/

Headers:

Content-Type: application/x-www-form-urlencoded

Body:

grant_type=client_credentials
client_id=YOUR_CLIENT_ID
client_secret=YOUR_CLIENT_SECRET

Reach out to your PersivX instance admin to obtain the CLIENT_ID and CLIENT_SECRET for your application.

Response:

{
  "access_token": "your-access-token",
  "token_type": "Bearer",
  "expires_in": 3600
}

📥 The Data API

Fetches data from any data source connected to PersivX. Each datasource connected to PersivX has a unique id, available in the PerisvX Report Designer UI.

Endpoint

POST https://app.persivx.com/api/queryDatasource/

Request Headers

Authorization: Bearer your-access-token  

Request Body Example

{
  "dataSourceId": PERSIVX_DATASOURCE_ID,
  "query": "SELECT client_name, SUM(bill_total) as sale_total FROM sales_summary WHERE region = 'West'",
  "responseFormat": 'JSON'
}

Supported response formats include 'JSON', 'XML', 'CSV' and 'PARQUET'. We are always looking to expand this library. If you do not see your required format, please reach out to our team at info@persivx.com and we will collaborate with you to build for your usecase.

Response Example

{
  "requestProcessed": True,
  "data": [
    {
      'client_name': 'Client A',
      'sale_total': 1302977.08
    },
    {
      'client_name': 'Client B',
      'sale_total': 16669.00
    },
    {
      'client_name': 'Client C',
      'sale_total': 169970.25
    }
  ]
}

---

🔒 Security

• All endpoints are HTTPS-only.
• OAuth 2.0 tokens are short-lived and scoped per client.
• API access is restricted by IP and/or domain. Reach out to your admin to whitelist your domain and/or IP.

---

🔒 Rate limits and query timeouts

Rate Limits:

• PersivX Instance Limits: 30 requests per minute.
• Deployed Instance: Instance admins can update rate limit. (Default: 30 request per minute)

Query Timeout:

• PersivX Instance Limits: 15 seconds per query.
• Deployed Instance: Instance admins can update Query Timeouts. (Default: 15 seconds per query)

---

✅ Best Practices

• Ensure your token is refreshed when expires_in time elapses.
• Avoid running queries that perform full table scans unless required.
• Use pagination (with limit and offset) for large datasets.
• When queries return more than 100,000 rows, PARQUET is the recommended response format.

---

⚙️ Query Generation with PersivX

The API request must specify what columns are required and what filters must be applied. PersivX takes care of the rest.

PersivX will generate optimized queries and return the results based on:

• Known schema relationships (foreign keys, primary keys, as well as user definend on PersivX layer)
• Available Indexes
• Large dataset optimizations
• Cross-database querying and merging

This provides a complete data abstraction layer for external applications, so they can focus on building their workflows, while PersivX does all the data fetching heavy-lifting.

Detailed docs comming soon...

---

📞 Support

Need help integrating the API? Reach out to our team at info@persivx.com for technical guidance, access credentials on PersivX Instance, or enterprise onboarding.