API Reference

Complete API documentation for integrating Dafthunk workflows into your applications, with examples in multiple programming languages.

Base URL

All API requests should be made to:

https://api.dafthunk.com

Authentication

API requests are authenticated using API keys. You can generate and manage your API keys from the Dafthunk dashboard under Settings → API Keys. Once you create a new API key, give it a descriptive name and ensure you copy and store it securely, as it won't be shown again.

To authenticate your requests, include the API key in the Authorization header, using the Bearer scheme:

Authorization: Bearer YOUR_API_KEY

HTTP Trigger Execution

Execute Workflow

Trigger a workflow that has an HTTP trigger node. The workflow id is the handle, so the URL is derived directly from the workflow. The workflow must be enabled. A http-request trigger runs synchronously; a http-webhook trigger runs asynchronously and returns an execution id immediately.

Route: GET or POST /http/{workflowId}

Request Body

The full request — method, headers, query parameters, and body — is passed to the workflow and exposed through the HTTP Request (or HTTP Webhook) trigger node's outputs. The body can be any content type; the example below sends JSON.

{
  "parameter1": "value1",
  "parameter2": "value2",
  "file_url": "https://example.com/file.pdf"
}

Response

{
  "id": "exec_1234567890",
  "workflowId": "wf_123",
  "status": "submitted",
  "nodeExecutions": [
    {
      "nodeId": "node_1",
      "status": "executing"
    }
  ]
}

Code Examples

curl -X POST "https://api.dafthunk.com/http/my-workflow-id" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "value" }'

const response = await fetch("https://api.dafthunk.com/http/my-workflow-id", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ "key": "value" })
});

const data = await response.json();
console.log(data);

import requests
import json

url = "https://api.dafthunk.com/http/my-workflow-id"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = json.dumps({ "key": "value" })
response = requests.post(url, headers=headers, data=payload)

print(response.json())

Execution Status

Get Execution Status

Check execution status and retrieve results from completed workflows.

Route: GET /{orgId}/executions/{executionId}

Response

{
  "execution": {
    "id": "exec_1234567890",
    "workflowId": "wf_123",
    "workflowName": "My Workflow",
    "status": "completed",
    "nodeExecutions": [
      {
        "nodeId": "node_1",
        "status": "completed",
        "outputs": {
          "result": "Generated result data"
        }
      }
    ],
    "startedAt": "2024-01-15T10:30:00.000Z",
    "endedAt": "2024-01-15T10:31:23.000Z"
  }
}

Code Examples

curl -X GET "https://api.dafthunk.com/your-org/executions/YOUR_EXECUTION_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://api.dafthunk.com/your-org/executions/YOUR_EXECUTION_ID", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

const data = await response.json();
console.log(data);

import requests

url = "https://api.dafthunk.com/your-org/executions/YOUR_EXECUTION_ID"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, headers=headers)

print(response.json())

Status Values

Status	Description
`idle`	Execution not yet started
`submitted`	Execution has been submitted
`executing`	Currently executing
`completed`	Successfully finished
`error`	Execution failed
`cancelled`	Execution was cancelled
`paused`	Execution is paused

Object Retrieval

Get Object

Retrieve binary or structured data objects generated by workflow executions.

Route: GET /{orgId}/objects?id={objectId}&mimeType={mimeType}

Query Parameters

Parameter	Type	Description
`id`	string	The unique identifier of the object
`mimeType`	string	The MIME type of the object (e.g., image/png, application/json)

Code Examples

curl -X GET "https://api.dafthunk.com/your-org/objects?id=YOUR_OBJECT_ID&mimeType=YOUR_OBJECT_MIME_TYPE" \
  -H "Authorization: Bearer YOUR_API_KEY"

const response = await fetch("https://api.dafthunk.com/your-org/objects?id=YOUR_OBJECT_ID&mimeType=YOUR_OBJECT_MIME_TYPE", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY"
  }
});

// Depending on the object's mimeType, you may need to handle the response differently
// For example, for an image:
// const blob = await response.blob();
// const imageUrl = URL.createObjectURL(blob);
// console.log(imageUrl);

// For JSON:
// const data = await response.json();
// console.log(data);

// For text:
// const text = await response.text();
// console.log(text);

if (response.ok) {
  console.log("Object fetched successfully. Handle response based on mimeType.");
} else {
  console.error("Error fetching object:", response.status, await response.text());
}

import requests

url = "https://api.dafthunk.com/your-org/objects?id=YOUR_OBJECT_ID&mimeType=YOUR_OBJECT_MIME_TYPE"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
response = requests.get(url, headers=headers)

if response.status_code == 200:
    # Depending on the object's mimeType, you might want to save it to a file
    # or process it in memory.
    # For example, to save to a file:
    # with open("downloaded_object.ext", "wb") as f: # replace .ext with actual extension
    #     f.write(response.content)
    print("Object fetched successfully. Content length:", len(response.content))
else:
    print(f"Error fetching object: {response.status_code}")
    print(response.text)

Queue Publishing

Publish Message

Publish a message to a queue. Workflows with queue triggers connected to this queue will be executed with the message payload.

Route: POST /queues/{queueId}/publish

Request Body

{
  "payload": {
    "event": "order_created",
    "data": { "id": 123 }
  }
}

Response

{
  "success": true,
  "queueId": "queue_123",
  "timestamp": 1705312200000
}

Code Examples

curl -X POST "https://api.dafthunk.com/queues/my-queue/publish" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payload": { "event": "order_created", "data": { "id": 123 } } }'

const response = await fetch("https://api.dafthunk.com/queues/my-queue/publish", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    payload: { event: "order_created", data: { id: 123 } }
  })
});

const data = await response.json();
console.log(data);

import requests
import json

url = "https://api.dafthunk.com/queues/my-queue/publish"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = json.dumps({
    "payload": { "event": "order_created", "data": { "id": 123 } }
})
response = requests.post(url, headers=headers, data=payload)

print(response.json())

Database Query

Execute Query

Execute a SQL query against a database. Databases are created in the Dafthunk dashboard under Databases.

Route: POST /{orgId}/databases/{databaseId}/query

Request Body

Field	Type	Required	Description
`sql`	string	Yes	SQL query to execute
`params`	array	No	Query parameters for prepared statements

{
  "sql": "SELECT * FROM users WHERE active = ?",
  "params": [true]
}

Code Examples

curl -X POST "https://api.dafthunk.com/your-org/databases/my-database/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sql": "SELECT * FROM users WHERE active = ?", "params": [true] }'

const response = await fetch("https://api.dafthunk.com/your-org/databases/my-database/query", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    sql: "SELECT * FROM users WHERE active = ?",
    params: [true]
  })
});

const data = await response.json();
console.log(data);

import requests
import json

url = "https://api.dafthunk.com/your-org/databases/my-database/query"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = json.dumps({
    "sql": "SELECT * FROM users WHERE active = ?",
    "params": [True]
})
response = requests.post(url, headers=headers, data=payload)

print(response.json())

Error Handling

The API uses conventional HTTP status codes:

Code	Description
`200`	Success
`201`	Created (returned by execute and publish endpoints)
`400`	Bad Request (invalid parameters)
`401`	Unauthorized (invalid API key)
`404`	Not Found (resource not found)
`429`	Too Many Requests (rate limit exceeded)
`500`	Internal Server Error