API Access

Definity provides comprehensive REST APIs for programmatic access to all platform features.

• API Documentation: All endpoints are documented in the Swagger UI at https://[definity-server]/api/docs
• Direct Database Access: Not recommended - schemas may change between versions

Authentication

All API requests require authentication via Bearer token in the Authorization header:

Authorization: Bearer <your_token>

Generate tokens in the Definity UI under User → Generate API Token.

Data Retrieval APIs

GET /api/*

Query pipelines, tasks, metrics, and lineage data from Definity. See the Swagger documentation for full endpoint details.

Reporting APIs

POST /log/*

Report task runs, transformations, and metric values to definity platform. This allows you to integrate external pipelines and metrics for unified observability.

Basic Flow

1. Start task: POST /log/task with status: "start"
2. Report metrics: POST /log/metrics with metric values
3. End task: POST /log/task with status: "end"

Example

import requests
import json
from datetime import datetime

# Configuration
HOST_URL = "https://app.definity.run"
headers = {"Authorization": "Bearer <your_token>"}
TASK_ID = datetime.now()  # Must be unique across all tasks

# 1. Start task
start_payload = {
    "task_id": TASK_ID,
    "status": "start",
    "env": "dev",
    "app_name": "demo-pipeline",
    "task_name": "basic_example",
    "task_type": "python",
    "app_pit": "2025-09-01"
}
requests.post(f"{HOST_URL}/log/task", headers=headers, json=start_payload)

# 2. Report metrics
metrics = {
    "asset_name": "basic_asset_example",
    "asset_type": "table",
    "metric_type": "cnt",
    "value": 12345
}

metrics_payload = {
    "task_id": TASK_ID,
    "metrics": [metrics]
}
requests.post(f"{HOST_URL}/log/metrics", headers=headers, json=metrics_payload)

# 3. End task
end_payload = {
    "task_id": TASK_ID,
    "status": "end"
}
requests.post(f"{HOST_URL}/log/task", headers=headers, json=end_payload)

Important: You must generate and manage unique task_id values. Use the same task_id across all API calls for a given task run.