API Overview

The TDMP API provides programmatic access to all platform features. Use it to automate dataset generation, integrate with CI/CD pipelines, manage projects and schemas, and build custom workflows.

Interactive API reference

Explore the full API documentation with an interactive client:

📚 API Reference

Interactive OpenAPI documentation with request/response examples and a built-in API client for testing endpoints directly in your browser.

Open API Reference →

Getting started

Base URL

The API base URL depends on your deployment:

• Development: http://localhost:8010
• Production: Contact your administrator for the correct URL

All endpoints are prefixed with the base URL. For example: http://localhost:8010/users/me

Authentication

The API uses JWT (JSON Web Token) authentication with Bearer tokens.

Step 1: Obtain a token

curl -X POST http://localhost:8010/users/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your-username&password=your-password"

Response:

{
  "access_token": "<token>",
  "token_type": "bearer"
}

Step 2: Use the token in requests

Include the token in the Authorization header for all subsequent API calls:

curl http://localhost:8010/users/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token expiration

Tokens expire after 24 hours by default. When a token expires, obtain a new one using the login endpoint.

Request format

HTTP methods: Standard REST methods (GET, POST, PUT, DELETE)

Content type: application/json for request bodies

Request body: JSON format

Example POST request:

curl -X POST http://localhost:8010/projects/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Test Project",
    "description": "Automated testing project"
  }'

Response format

Content type: application/json

Success responses: HTTP 200 (OK) or 201 (Created)

Error responses: Include status code and error details

Example success response:

{
  "project_id": 123,
  "name": "My Test Project",
  "description": "Automated testing project",
  "created_at": "2026-01-06T10:30:00Z"
}

Example error response:

{
  "detail": "Project not found"
}

HTTP status codes

Success codes:

• 200 OK – Request succeeded
• 201 Created – Resource created successfully

Client error codes:

• 400 Bad Request – Invalid request data (missing required fields, malformed JSON)
• 401 Unauthorized – Missing or invalid authentication token
• 403 Forbidden – Insufficient permissions (e.g., Tester trying to delete a project)
• 404 Not Found – Resource does not exist
• 422 Unprocessable Entity – Validation error (e.g., invalid email format, constraint conflicts)

Server error codes:

• 500 Internal Server Error – Unexpected server-side error

API endpoints by category

Authentication

POST /users/token – Login and obtain access token

Required fields: username, password (form-encoded)

GET /users/me – Get current user information

Returns: id, username, role, tenant_id, projects

GET /users/logout – Logout (invalidates session)

User management

POST /users/create – Create new user (Admin/SuperUser only)

GET /users – Search users in tenant

GET /users/{user_id} – Get user details

PATCH /users/{user_id} – Update user (change role, activate/deactivate)

POST /users/setup-password – Set password using invitation token

Projects

POST /projects/create – Create new project (Manager/Admin/SuperUser)

GET /projects – List all accessible projects

GET /projects/{project_id} – Get project details (members, schemas, datasets)

PUT /projects/{project_id} – Update project name, description, or tags

DELETE /projects/{project_id} – Delete project (Admin only)

POST /projects/{project_id}/add-user – Add member to project

POST /projects/{project_id}/remove-user – Remove member from project

POST /projects/{project_id}/add-schema – Link schema to project

Schemas

POST /schemas – Upload new schema (XSD, JSON Schema)

GET /schemas – List schemas in tenant

GET /schemas/{schema_id} – Get schema details

GET /schemas/{schema_id}/repr – Get schema representation for constraint building

DELETE /schemas/{schema_id} – Delete schema

Constraint sets

POST /constraints – Create constraint set

GET /constraints – List constraint sets

GET /constraints/{constraint_id} – Get constraint set details

PUT /constraints/{constraint_id} – Update constraint set

DELETE /constraints/{constraint_id} – Delete constraint set

Datasets

POST /datasets/create – Create dataset and trigger generation

Required fields: name, project_id, schema_id, record_count

Optional fields: constraint_set_id, types (output formats), params (generation parameters)

GET /datasets – List all datasets

GET /datasets/{dataset_id} – Get dataset details and status

DELETE /datasets/{dataset_id} – Delete dataset

GET /datasets/generate/{dataset_id} – Manually trigger generation (if queued)

POST /datasets/{dataset_id}/export-s3 – Export dataset to S3 integration

Data (file downloads)

GET /data/{dataset_id} – Download generated dataset files

Query parameters: format (csv, json, xml, sql), file_index (for multi-file datasets)

Notifications

GET /notifications – Get in-app notifications for current user

DELETE /notifications/{notification_id} – Mark notification as read/delete

GET /notifications/unread-count – Get count of unread notifications

Settings

GET /settings – Get user settings

PUT /settings – Update user profile (name, theme)

POST /settings/avatar – Upload avatar image

POST /settings/change_password – Change password

POST /settings/change_email – Update email address

POST /settings/notifications – Update notification preferences

POST /settings/enable_2fa – Enable two-factor authentication

POST /settings/disable_2fa – Disable two-factor authentication

POST /settings/delete – Delete user account

Audit logs

GET /audit/logs – Get audit logs (Admin/SuperUser only)

Query parameters: action, actor_id, role, project_id, start_date, end_date

Tenants

GET /tenants – Get current tenant information

GET /tenants/{tenant_id} – Get tenant details (SuperUser only)

PUT /tenants/{tenant_id} – Update tenant settings (SuperUser only)

Integrations

GET /integrations/providers – List available integration providers

GET /integrations – List configured integrations

POST /integrations – Create new integration

PUT /integrations/{integration_id} – Update integration configuration

DELETE /integrations/{integration_id} – Remove integration

POST /integrations/{integration_id}/test – Test integration connection

Common workflows

Automated dataset generation

Typical CI/CD pipeline workflow:

1. Authenticate: Obtain API token using service account credentials
2. List projects: Find the project ID for your testing project
3. Create dataset: POST to /datasets/create with schema and constraints
4. Poll status: GET /datasets/{id} periodically to check generation status
5. Download: GET /data/{id} when status is "completed"
6. Use in tests: Feed downloaded data into your test framework

Example script (simplified):

#!/bin/bash
TOKEN=$(curl -s -X POST http://localhost:8010/users/token \
  -d "username=ci-service&password=$CI_PASSWORD" \
  | jq -r '.access_token')

DATASET=$(curl -s -X POST http://localhost:8010/datasets/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Build #'$BUILD_ID'",
    "project_id": 5,
    "schema_id": 12,
    "constraint_set_id": 8,
    "record_count": 100,
    "types": ["json"]
  }' | jq -r '.dataset_id')

# Poll until complete
while true; do
  STATUS=$(curl -s http://localhost:8010/datasets/$DATASET \
    -H "Authorization: Bearer $TOKEN" \
    | jq -r '.status')

  if [ "$STATUS" = "completed" ]; then
    break
  elif [ "$STATUS" = "failed" ]; then
    exit 1
  fi

  sleep 5
done

# Download dataset
curl -o test-data.json http://localhost:8010/data/$DATASET?format=json \
  -H "Authorization: Bearer $TOKEN"

Creating and managing projects

# Create project
PROJECT_ID=$(curl -X POST http://localhost:8010/projects/create \
  -H "Authorization: Bearer $TOKEN"
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App Testing",
    "description": "Test data for mobile app regression suite"
  }' | jq -r '.project_id')

# Add team members
curl -X POST http://localhost:8010/projects/$PROJECT_ID/add-user \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": 42, "role": "edit"}'

# Link schema to project
curl -X POST http://localhost:8010/projects/$PROJECT_ID/add-schema \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": 15}'

Bulk operations

Automate repetitive tasks:

import requests

BASE_URL = "http://localhost:8010"
TOKEN = "your-token-here"
HEADERS = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Generate multiple datasets
schemas = [10, 11, 12, 13, 14]
project_id = 7
constraint_set_id = 20

for schema_id in schemas:
    response = requests.post(
        f"{BASE_URL}/datasets/create",
        headers=HEADERS,
        json={
            "name": f"Batch Dataset for Schema {schema_id}",
            "project_id": project_id,
            "schema_id": schema_id,
            "constraint_set_id": constraint_set_id,
            "record_count": 50,
            "types": ["csv", "json"]
        }
    )
    print(f"Created dataset {response.json()['dataset_id']}")

Rate limiting and best practices

Polling: When checking dataset status, use reasonable intervals (5-10 seconds). Avoid sub-second polling.

Pagination: For list endpoints, use limit and offset query parameters to paginate results (not all endpoints support this yet—check interactive docs).

Error handling: Always check HTTP status codes and handle errors gracefully. Log detail field from error responses for debugging.

Token management: Store tokens securely. For CI/CD, use environment variables or secret management tools. Refresh tokens when they expire.

Idempotency: Dataset creation is not idempotent—repeated calls create new datasets. Use unique naming conventions (e.g., include build ID or timestamp) to track generated datasets.

Concurrency: The API handles concurrent requests. You can generate multiple datasets in parallel, but respect system resources and avoid overwhelming the server.

Role-based access

API endpoints enforce the same role-based permissions as the web interface:

Tester: Can create datasets, view projects they belong to, download data

Manager: Can create projects, manage project members, invite users

Admin: Full tenant management, user administration, access to audit logs

SuperUser: Multi-tenant access, all Admin privileges across all tenants

If you receive a 403 Forbidden error, your role lacks permission for that operation.

Webhooks and event notifications

Some deployments support webhook integrations configured via /integrations:

• dataset.completed: Triggered when dataset generation finishes
• dataset.failed: Triggered when generation fails
• schema.uploaded: Triggered when new schema is added
• project.created: Triggered when new project is created

Configure webhooks in the Integrations page or via the API to receive POST requests at your specified URL.

Troubleshooting

"401 Unauthorized": Token is missing, invalid, or expired. Obtain a new token.

"403 Forbidden": Your role lacks permission. Contact an Admin to adjust your permissions.

"404 Not Found": Resource ID is incorrect, or you lack access. Verify the ID and your project membership.

"422 Unprocessable Entity": Validation error. Check the detail field for specific issues (e.g., missing required fields, invalid values).

"500 Internal Server Error": Server-side issue. Check logs or contact support. May indicate constraint conflicts, generation errors, or configuration problems.

Additional resources

Interactive API docs: /api/reference

Sample scripts: Check your deployment's documentation for language-specific examples (Python, JavaScript, Bash, etc.)

Support: Contact your administrator or refer to internal documentation for deployment-specific details (base URL, service accounts, integration options)