Skip to main content
Beta. The Taps API is stable but may add fields or refine response shapes in upcoming releases. Existing endpoints will remain backward-compatible where possible.

​
List Taps

GET /api/v1/taps
Returns all registered taps. Response: JSON array of tap configurations.

​
Get Tap

GET /api/v1/tap?name={tapName}
Returns a single tap configuration, including the script content from MinIO. Parameters:
ParameterTypeDescription
namequeryTap name (required)

​
Create or Update Tap

POST /api/v1/tap
Content-Type: application/json
Body: 
{
  "name": "stock-prices-tap",
  "description": "Fetch daily stock prices from yfinance",
  "scriptPath": "tap-scripts/stock-prices-tap_a1b2c3d4.py",
  "targetPipeline": "stock-prices-pipeline",
  "packages": ["yfinance"],
  "secretName": "my-api-creds",
  "cronExpression": "0 0 0 * * ?",
  "enabled": true
}

​
Delete Tap

DELETE /api/v1/tap?name={tapName}
Deletes the tap configuration and its script from MinIO.

​
Brainstorm (AI Chat)

POST /api/v1/tap/brainstorm
Content-Type: application/json
Multi-turn conversational endpoint that helps the user refine a vague tap idea into a clear instruction. The UI calls this on every message in the brainstorm chat panel of the tap creation wizard. The AI:
  • Asks one focused clarifying question at a time
  • Suggests specific data sources (e.g., yfinance, Alpha Vantage, Open-Meteo)
  • Recognizes Datris platform tables and uses the metadata/query endpoints
  • Returns an updated instruction draft on every turn so the UI can keep the instruction box in sync
  • Returns suggestedEnvVars when an external API requires authentication
Body: 
{
  "messages": [
    {"role": "user", "content": "I'm looking for company earnings data"},
    {"role": "assistant", "content": "Which companies?..."},
    {"role": "user", "content": "Tickers from the consumer_discretionary_earnings table on Datris"}
  ],
  "currentDescription": "Optional: the current draft instruction so the AI has context"
}
Response: 
{
  "reply": "Got it. Which earnings data source — yfinance (free), Alpha Vantage, or Polygon.io?",
  "description": "Query the consumer_discretionary_earnings table via /api/v1/query/postgres to get the ticker list. (Source TBD.)",
  "suggestedEnvVars": []
}
After the user picks Alpha Vantage, a subsequent call returns: 
{
  "reply": "Good choice. The script will need an Alpha Vantage API key — please create a tap secret with ALPHA_VANTAGE_API_KEY in the credentials section below.",
  "description": "Query the consumer_discretionary_earnings table via /api/v1/query/postgres to get tickers, then for each ticker call the Alpha Vantage EARNINGS endpoint and return historical earnings records. Use os.environ.get('ALPHA_VANTAGE_API_KEY') for authentication.",
  "suggestedEnvVars": ["ALPHA_VANTAGE_API_KEY"]
}
The AI never suggests DATRIS_POSTGRES_DATABASE, DATRIS_MONGODB_DATABASE, DATRIS_PLATFORM_HOST, or DATRIS_PLATFORM_PORT in suggestedEnvVars — those are always injected by the platform.

​
Generate Script (AI)

POST /api/v1/tap/generate
Content-Type: application/json
Uses AI to generate a Python fetch() script from a plain-English description. Body: 
{
  "description": "Fetch daily stock prices for S&P 500 from yfinance",
  "tapName": "stock-prices-tap",
  "oldScriptPath": "tap-scripts/old_script.py",
  "secretName": "my-api-creds"
}
Response: 
{
  "script": "import requests\n\ndef fetch():\n    ...",
  "packages": ["yfinance"],
  "scriptPath": "tap-scripts/stock-prices-tap_a1b2c3d4.py"
}

​
Fix Script (AI Diagnosis)

POST /api/v1/tap/fix
Content-Type: application/json
Uses AI to fix a script based on a diagnosis of what went wrong. Body: 
{
  "tapName": "stock-prices-tap",
  "script": "current script content...",
  "diagnosis": "The API endpoint is wrong...",
  "logs": "script output logs...",
  "error": "error message...",
  "oldScriptPath": "tap-scripts/old_script.py"
}
Response: Same format as Generate Script.

​
Test Tap

POST /api/v1/tap/test
Content-Type: application/json
Executes the tap script without sending data to a pipeline. Returns results, logs, and AI diagnosis if issues detected. Body: A TapConfig JSON object (same as Create). Response: 
{
  "records": [{"ticker": "AAPL", "close": 255.92}, ...],
  "recordCount": 503,
  "dataType": "csv",
  "columns": ["ticker", "date", "open", "high", "low", "close", "volume"],
  "logs": "Retrieved 503 tickers...\nBatch 1/11...",
  "error": null,
  "aiExplanation": null
}
If errors or 0 records are detected, aiExplanation contains an AI-generated diagnosis. For dataType: "csv", column names in columns and the keys inside each record in records are normalized by the platform: lowercase, [a-z0-9_] only, with % rewritten to percent. Source data with names like EPS Estimate or Surprise(%) will appear as eps_estimate and surprise_percent. JSON/XML results destined for MongoDB are not normalized. See Schema Definition → Column Naming Rules.

​
Run Tap

POST /api/v1/tap/run
Content-Type: application/json
Executes a saved tap. Optionally sends data to the configured pipeline. Body: 
{
  "name": "stock-prices-tap",
  "pushToPipeline": "true"
}
Response: 
{
  "tap": "stock-prices-tap",
  "description": "Fetch daily stock prices...",
  "status": "success",
  "records": [...],
  "recordCount": 503,
  "dataType": "csv",
  "logs": "...",
  "error": null
}

​
Generate CRON Expression (AI)

POST /api/v1/tap/cron
Content-Type: application/json
Converts a plain-English schedule description to a Quartz CRON expression. Body: 
{
  "description": "Every weekday at 4pm ET"
}
Response: 
{
  "cronExpression": "0 0 16 ? * MON-FRI"
}

​
Run History

GET /api/v1/tap/logs?name={tapName}
Returns the last 50 run log entries for a tap, sorted by most recent first. Response: 
[
  {
    "tapName": "stock-prices-tap",
    "runTime": "2026-04-04T20:23:22Z",
    "status": "success",
    "recordCount": 503,
    "dataType": "csv",
    "logs": "Retrieved 503 tickers...",
    "error": null,
    "pushToPipeline": false,
    "durationMs": 45000
  }
]

​
Authentication

All endpoints require the x-api-key header if API key authentication is enabled.