Workflows

The Workflows API allows you to run workflows (multi-step AI pipelines) built in the Hatz platform. Workflows execute asynchronously -- you submit a run request and then poll for the job status to get results.

Run a Workflow

Submit a workflow for execution. The workflow runs asynchronously in the background. Use the returned job_id to poll for status and results.

Endpoint

POST /v1/workflows/run

Request Body

• app_id (required): The UUID of the workflow to run
• inputs (required): Key-value object of user inputs, where keys are the variable_name defined on the workflow's input fields (same format as the App Builder query endpoint)
• is_draft_app (optional): Whether to run the draft version of the workflow (default: false)

File Inputs

If a workflow has an input of type file_upload, you can pass a file UUID (obtained from the File Upload endpoint) as the value for that input. The workflow step will then have access to the file contents.

When uploading a file for use in a workflow, we recommend including scope_type and scope_id in the upload request so the file is properly registered:

curl 'https://ai.hatz.ai/v1/files/upload' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  --form 'file=@"report.csv"' \
  --form 'scope_type="workflow"' \
  --form 'scope_id="5ae6e9dd-0296-4409-8fe4-1fc646bb22f7"'

Then pass the returned file_uuid in the workflow's inputs.

Example Request

curl -X POST 'https://ai.hatz.ai/v1/workflows/run' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "app_id": "5ae6e9dd-0296-4409-8fe4-1fc646bb22f7",
    "inputs": {
      "topic": "machine learning",
      "audience": "beginners"
    }
  }'

Example with a file input:

curl -X POST 'https://ai.hatz.ai/v1/workflows/run' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "app_id": "5ae6e9dd-0296-4409-8fe4-1fc646bb22f7",
    "inputs": {
      "report_file": "8fb5bc1d-5a8d-4015-86a6-b0ca394e7793",
      "summary_style": "executive"
    }
  }'

Response

{
  "status": "Workflow Job Invoked",
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

The workflow is now running in the background. Use the job_id to check its progress.

Get Workflow Job Status

Poll this endpoint to check the status of a running workflow and retrieve its step outputs once complete.

Endpoint

GET /v1/workflows/{job_id}

Path Parameters

• job_id (required): The job ID returned from the run endpoint

Example Request

curl 'https://ai.hatz.ai/v1/workflows/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'X-API-Key: $HATZ_API_KEY'

Response

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "app_id": "5ae6e9dd-0296-4409-8fe4-1fc646bb22f7",
  "tenant_id": "tenant_9x2AbC123",
  "user_id": "user-uuid",
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:00:30Z",
  "start_time": 1736935200000,
  "end_time": 1736935230000,
  "number_of_steps": 3,
  "status": "complete",
  "user_inputs": {
    "topic": "machine learning",
    "audience": "beginners"
  },
  "app_data": { },
  "step_outputs": [
    {
      "step_id": "step-1-uuid",
      "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "step_type": "prompt",
      "status": "complete",
      "output_type": "dump",
      "created_at": "2025-01-15T10:00:05Z",
      "updated_at": "2025-01-15T10:00:15Z",
      "start_time": 1736935205000,
      "end_time": 1736935215000,
      "duration": 10000,
      "output_data": "Step 1 output text...",
      "payload": {}
    },
    {
      "step_id": "step-2-uuid",
      "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "step_type": "prompt",
      "status": "complete",
      "output_type": "dump",
      "created_at": "2025-01-15T10:00:15Z",
      "updated_at": "2025-01-15T10:00:30Z",
      "start_time": 1736935215000,
      "end_time": 1736935230000,
      "duration": 15000,
      "output_data": "Step 2 output text...",
      "payload": {}
    }
  ]
}

Job Status Values

Polling Recommendation

Since workflows run asynchronously, poll the status endpoint to check for completion. A reasonable approach is to start polling after a short delay (e.g., 2 seconds) and then check every few seconds until the status is complete or failed.

Get Presigned URL for Workflow Output

If a workflow step produces a document (e.g., a generated file), you can get a temporary download URL for it.

Endpoint

POST /v1/workflows/presigned-url

Request Body

• job_id (required): The workflow job run ID
• step_id (required): The step ID whose output contains the file
• expires_in (optional): URL expiration in seconds (default: 3600)

Example Request

curl -X POST 'https://ai.hatz.ai/v1/workflows/presigned-url' \
  -H 'X-API-Key: $HATZ_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "step_id": "step-2-uuid",
    "expires_in": 3600
  }'

Response

{
  "url": "https://s3.amazonaws.com/...",
  "expires_in": 3600
}

Error Responses

404 Not Found

{
  "detail": "Job not found"
}

429 Too Many Requests

Returned when your organization has exceeded its credit limit:

{
  "detail": "Workflows have been rate limited for your organization due to a credit overage."
}