Overview
Endpoints allow you to create custom API interfaces with secure, controlled access. You can define two types of endpoints:
- Query Endpoints - Execute SQL queries on your datasets with dynamic filters
- Action Endpoints - Execute serverless Python functions for custom logic
Creating Endpoints
- Navigate to your Project
- Create a new YAML file for your endpoint (e.g.,
api-orders.yaml)
- Define your endpoint configuration
- Reference it in your
config.yaml file
Endpoint Types
Query-Based Endpoints
Query endpoints execute SQL queries on your data with dynamic filtering using Jinja templating.
Example YAML Configuration:
endpoints:
- name: consolidated-sales-endpoint
type: query
config:
filters:
- name: country
type: string
optional: true
- name: city
type: string
optional: true
query: |
SELECT *
FROM consolidated_sales_df_299ceb
WHERE 1 = 1
{% if country is defined %}
AND CustomerCountry = '{{ country }}'
{% endif %}
{% if city is defined %}
AND CustomerCity = '{{ city }}'
{% endif %}
Action-Based Endpoints
Action endpoints execute serverless Python functions when called. Perfect for sending notifications, processing data, calling external APIs, or automating workflows.
Example YAML Configuration:
endpoints:
- name: process-data-endpoint
type: action
config:
action_id: "507f1f77bcf86cd799439011"
The action_id references an action function in your project. Get the ID from your action details page.
Register in config.yaml
Reference your endpoint file in config.yaml:
project_name: TestProject
project_id: 688b3d0b7c5f93f0763a028c
endpoints:
- path: api-orders.yaml
Configuration Reference
Common Attributes
| Attribute | Type | Required | Description |
|---|
name | string | Yes | Unique endpoint identifier |
type | string | Yes | Endpoint type: query or action |
config | object | Yes | Type-specific configuration |
Query Config Attributes
| Attribute | Type | Required | Description |
|---|
query | string | Yes | SQL query with Jinja templating |
filters | array | No | List of filter parameters |
Action Config Attributes
| Attribute | Type | Required | Description |
|---|
action_id | string | Yes | Action function ID to execute |
Filter Configuration
Filters are only for query endpoints and define dynamic parameters:
| Attribute | Type | Required | Description |
|---|
name | string | Yes | Filter parameter name (alphanumeric, -, _) |
type | string | Yes | Data type (see types below) |
optional | boolean | No | Whether filter is optional (default: true) |
Filter Types
| Type | Description | Example Usage |
|---|
string | Text parameter | country, category |
integer | Numeric parameter | year, limit |
float | Decimal parameter | price, rating |
date | Date parameter | start_date, end_date |
datetime | DateTime parameter | created_at, updated_at |
boolean | Boolean parameter | active, is_featured |
enum | Enumeration parameter | status, priority |
Using Endpoints
All endpoints are accessible via HTTP GET requests with parameters passed as query parameters:
curl -X GET \
"https://app.datazone.co/api/v1/endpoint/your-endpoint-name?param1=value1¶m2=value2" \
-H "x-api-key: <DATAZONE_API_KEY>" \
-H "Content-Type: application/json"
Query Endpoint Response
Query endpoints return JSON data with query results:
{
"records": [
{
"column1": "value1",
"column2": "value2"
}
],
"metadata": {
"total_records": 100,
"query_time_ms": 250,
"endpoint_name": "consolidated-sales-endpoint"
}
}
Action Endpoint Response
Action endpoints return execution results:
{
"status": "success",
"execution_id": "65f3a2b8c4e1a9d0c8b4e7f3",
"message": "Action executed successfully",
"metadata": {
"action_id": "507f1f77bcf86cd799439011",
"endpoint_name": "process-data-endpoint",
"triggered_at": "2026-01-20T10:30:00Z"
}
}
Authentication
Endpoints use API key authentication via the x-api-key header:
-H "x-api-key: YOUR_API_KEY"
Error Responses
| Status Code | Description |
|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 403 | Forbidden - Access denied |
| 404 | Not Found - Endpoint doesn’t exist |
| 500 | Internal Server Error |
{
"error": "Invalid parameter 'country': must be a string",
"code": "INVALID_PARAMETER",
"status": 400
}
Advanced Query Features
Jinja Templating
Endpoints support Jinja templating for dynamic queries:
query: |
SELECT *
FROM sales_data
WHERE 1 = 1
{% if start_date is defined %}
AND order_date >= '{{ start_date }}'
{% endif %}
{% if end_date is defined %}
AND order_date <= '{{ end_date }}'
{% endif %}
{% if categories is defined %}
AND category IN ({{ categories | join("','") | surround("'") }})
{% endif %}
Caching
Endpoint responses can be cached:
- Default cache TTL: 60 minutes
- Cache headers indicate freshness
- Use cache-busting parameters when needed
