Skip to main content

Using Query APIs

Learn how to access and use the API endpoints generated by your saved queries.

API Endpoint Structure​

When you save a query, the system automatically generates a secure REST API endpoint:

GET /api/query/{query-name}

Example​

GET /api/query/monthly-sales-report

Authentication​

All query API endpoints require authentication using Bearer tokens.

Required Headers​

Authorization: Bearer your-api-token
Content-Type: application/json

Obtaining API Tokens​

  1. Navigate to Account Settings → API Tokens
  2. Click Generate New Token
  3. Provide a token description
  4. Copy and securely store the generated token
  5. The token will not be shown again

Token Permissions​

API tokens inherit the permissions of the user account:

  • Can only access queries for workflows the user has permission to view
  • Respects all data access restrictions
  • Subject to same security policies as the user account

Making API Requests​

Basic Request​

curl -X GET https://your-domain.com/api/query/monthly-sales-report \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json"

JavaScript Example​

const fetchQueryData = async () => {
  const response = await fetch('https://your-domain.com/api/query/monthly-sales-report', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer your-api-token',
      'Content-Type': 'application/json'
    }
  });
  
  const data = await response.json();
  return data;
};

Python Example​

import requests

headers = {
    'Authorization': 'Bearer your-api-token',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://your-domain.com/api/query/monthly-sales-report',
    headers=headers
)

data = response.json()

API Response Format​

Successful Response (200 OK)​

{
  "success": true,
  "data": [
    {
      "submission_id": "REQ-2024-001",
      "requester_name": {
        "value": "John Doe",
        "type": "textfield"
      },
      "amount": {
        "value": 5000,
        "type": "number"
      },
      "status": {
        "value": "Approved",
        "type": "select"
      }
    }
  ],
  "total_matches": 150,
  "page": 1,
  "per_page": 50,
  "aggregate": {
    "total_amount": 750000,
    "avg_amount": 5000,
    "count": 150
  }
}

Field Value Structure​

Each field in the response includes:

  • value: The actual field value
  • type: The field type (textfield, number, date, etc.)

Error Response (4xx/5xx)​

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired API token"
  }
}

Dynamic Parameters​

Override saved query settings by passing URL parameters.

Dynamic Filtering​

Add or override filters using the filters parameter:

GET /api/query/sales-report?filters[status][operation]=equals&filters[status][value]=Approved

Filter Parameter Structure​

filters[field_name][operation]=operation_type
filters[field_name][value]=filter_value

Multiple Filters Example​

GET /api/query/sales-report?
  filters[status][operation]=equals&
  filters[status][value]=Approved&
  filters[amount][operation]=greater_than&
  filters[amount][value]=1000

Dynamic Aggregations​

Override aggregations using the aggregates parameter:

GET /api/query/sales-report?aggregates[amount]=sum&aggregates[quantity]=avg

Available Aggregation Operations​

  • sum: Sum of values
  • avg: Average of values
  • min: Minimum value
  • max: Maximum value
  • count: Count of records
  • count_distinct: Count of unique values

Pagination​

Control result pagination:

GET /api/query/sales-report?page=2&per_page=100
  • page: Page number (default: 1)
  • per_page: Results per page (default: 50, max: 500)

Sorting​

Sort results by field:

GET /api/query/sales-report?sort_by=created_date&sort_order=desc
  • sort_by: Field name to sort by
  • sort_order: asc (ascending) or desc (descending)

Field Selection​

Limit returned fields:

GET /api/query/sales-report?fields=submission_id,amount,status

Complete Example​

Request​

curl -X GET "https://api.osprov.com/api/query/sales-report?\
filters[status][operation]=equals&\
filters[status][value]=Approved&\
filters[created_date][operation]=date_range&\
filters[created_date][from]=2024-01-01&\
filters[created_date][to]=2024-03-31&\
aggregates[amount]=sum&\
page=1&\
per_page=25&\
sort_by=amount&\
sort_order=desc" \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json"

Response​

{
  "success": true,
  "data": [
    {
      "submission_id": "REQ-2024-045",
      "amount": {
        "value": 15000,
        "type": "number"
      },
      "status": {
        "value": "Approved",
        "type": "select"
      },
      "created_date": {
        "value": "2024-02-15T10:30:00Z",
        "type": "datetime"
      }
    }
  ],
  "total_matches": 45,
  "page": 1,
  "per_page": 25,
  "aggregate": {
    "amount": 675000
  }
}

Rate Limiting​

API requests are subject to rate limiting:

  • Default Limit: 1000 requests per hour per API token
  • Burst Limit: 100 requests per minute
  • Headers Returned:
    • X-RateLimit-Limit: Maximum requests allowed
    • X-RateLimit-Remaining: Requests remaining
    • X-RateLimit-Reset: Time when limit resets (Unix timestamp)

Rate Limit Response (429)​

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "retry_after": 60
  }
}

Error Handling​

Common Error Codes​

CodeDescriptionSolution
401UnauthorizedCheck API token validity
403ForbiddenVerify permissions for the workflow
404Query Not FoundCheck query name spelling
422Invalid ParametersReview parameter format and values
429Rate LimitedWait and retry after specified time
500Server ErrorContact support if persists

Best Practices for Error Handling​

  1. Implement Retry Logic: For 429 and 503 errors
  2. Log Errors: Track error patterns
  3. Validate Parameters: Check values before sending
  4. Handle Timeouts: Set appropriate timeout values
  5. Cache Responses: Reduce unnecessary API calls

Security Considerations​

API Token Management​

  1. Never expose tokens in client-side code
  2. Rotate tokens regularly (recommended: every 90 days)
  3. Use environment variables for token storage
  4. Implement token encryption at rest
  5. Monitor token usage for anomalies

HTTPS Only​

All API requests must use HTTPS. HTTP requests will be rejected.

IP Whitelisting​

For additional security, configure IP whitelisting:

  1. Navigate to Account Settings → API Security
  2. Add trusted IP addresses or ranges
  3. Enable IP restriction for API access

Next Steps​