> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflows

> Automate multi-step OSINT workflows with triggers, conditions, and enrichment steps.

## Overview

Workflows let you chain multiple enrichment steps into automated pipelines. Trigger them manually, on a schedule, via webhook, or in response to monitor events.

### Key concepts

| Concept      | Description                                                                                  |
| ------------ | -------------------------------------------------------------------------------------------- |
| **Workflow** | A reusable automation with a trigger and a sequence of steps                                 |
| **Trigger**  | What starts the workflow: `manual`, `webhook`, `schedule`, `file_upload`, or `monitor_event` |
| **Step**     | An action in the pipeline: lookup, condition, delay, webhook, or transform                   |
| **Run**      | A single execution of a workflow with input data and step results                            |
| **Secret**   | Encrypted key-value pair available to webhook steps                                          |
| **Template** | Pre-built workflow you can clone and customize                                               |

### Step types

| Type             | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `email_lookup`   | Enrich an email address                              |
| `phone_lookup`   | Enrich a phone number                                |
| `company_lookup` | Enrich a company                                     |
| `domain_lookup`  | Domain intelligence                                  |
| `ip_lookup`      | IP geolocation & threat data                         |
| `darkweb_lookup` | Dark web breach search                               |
| `condition`      | Branch logic (if/else based on previous step output) |
| `delay`          | Wait a specified duration before continuing          |
| `webhook`        | Send HTTP request to an external URL                 |
| `transform`      | Transform/map data between steps                     |

### Trigger types

| Type            | Description                                               |
| --------------- | --------------------------------------------------------- |
| `manual`        | Triggered via API or dashboard button                     |
| `webhook`       | Triggered by an incoming HTTP POST to a unique ingest URL |
| `schedule`      | Runs on a cron schedule                                   |
| `file_upload`   | Triggered when a file is uploaded                         |
| `monitor_event` | Triggered when a monitor detects changes                  |

***

## API Endpoints

All workflow endpoints require JWT authentication (dashboard) or API key authentication.

### List Workflows

```bash theme={"dark"}
GET /api/workflows
```

**Query parameters:**

| Parameter | Type    | Description                                   |
| --------- | ------- | --------------------------------------------- |
| `page`    | integer | Page number (default: 1)                      |
| `limit`   | integer | Items per page (default: 20)                  |
| `status`  | string  | Filter by status: `active`, `paused`, `draft` |

**Example:**

```bash theme={"dark"}
curl "https://encrata.com/api/workflows?status=active" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

***

### Create Workflow

```bash theme={"dark"}
POST /api/workflows
```

**Body:**

| Field         | Type   | Required | Description                |
| ------------- | ------ | -------- | -------------------------- |
| `name`        | string | Yes      | Workflow name              |
| `description` | string | No       | Human-readable description |
| `trigger`     | object | No       | Trigger configuration      |
| `steps`       | array  | No       | Array of step objects      |
| `template_id` | string | No       | Clone from a template      |

**Example:**

```bash theme={"dark"}
curl -X POST "https://encrata.com/api/workflows" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enrich new leads",
    "description": "Look up email, then company, then send to webhook",
    "trigger": { "type": "webhook" },
    "steps": [
      { "id": "step1", "type": "email_lookup", "config": { "field": "email" } },
      { "id": "step2", "type": "company_lookup", "config": { "field": "step1.company" } },
      { "id": "step3", "type": "webhook", "config": { "url": "https://hooks.example.com/new-lead", "method": "POST" } }
    ]
  }'
```

***

### Get Workflow

```bash theme={"dark"}
GET /api/workflows/{id}
```

Returns the full workflow definition including trigger, steps, and metadata.

***

### Update Workflow

```bash theme={"dark"}
PUT /api/workflows/{id}
```

Updates the workflow. A new version is automatically created before the mutation (immutable version history).

**Body:** Same fields as Create.

***

### Delete Workflow

```bash theme={"dark"}
DELETE /api/workflows/{id}
```

Permanently deletes a workflow and all its run history.

***

### Trigger a Run

```bash theme={"dark"}
POST /api/workflows/{id}/run
```

Manually trigger a workflow execution. Supports idempotency.

**Headers:**

| Header            | Description                                   |
| ----------------- | --------------------------------------------- |
| `Idempotency-Key` | Optional. Prevents duplicate runs if retried. |

**Body:**

| Field   | Type   | Description                         |
| ------- | ------ | ----------------------------------- |
| `input` | object | Input data passed to the first step |

**Example:**

```bash theme={"dark"}
curl -X POST "https://encrata.com/api/workflows/wf_abc123/run" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "email": "jane@company.com" } }'
```

***

### Version History

```bash theme={"dark"}
GET /api/workflows/{id}/versions
```

Returns all immutable versions of a workflow (created automatically on each update).

***

### Audit Log

```bash theme={"dark"}
GET /api/workflows/{id}/audit
```

Returns the audit trail for a workflow (who created, updated, ran it and when).

***

### Webhook Token

```bash theme={"dark"}
GET /api/workflows/{id}/webhook-token
POST /api/workflows/{id}/webhook-token
```

Get or create a public ingest token. The token enables triggering the workflow via:

```
POST /api/workflows/ingest/{token}
```

This public endpoint requires no JWT anyone with the token can trigger the workflow.

***

## Runs

### List All Runs

```bash theme={"dark"}
GET /api/workflows/runs
```

**Query parameters:**

| Parameter     | Type    | Description                 |
| ------------- | ------- | --------------------------- |
| `page`        | integer | Page number                 |
| `limit`       | integer | Items per page              |
| `workflow_id` | string  | Filter by specific workflow |

***

### Get Run Detail

```bash theme={"dark"}
GET /api/workflows/runs/{id}
```

Returns the run with step-by-step results, timing, and status.

***

### Cancel a Run

```bash theme={"dark"}
POST /api/workflows/runs/{id}/cancel
```

Cancels a currently executing run.

***

### Delete a Run

```bash theme={"dark"}
DELETE /api/workflows/runs/{id}
```

Deletes a completed or failed run.

***

## Templates

### List Templates

```bash theme={"dark"}
GET /api/workflows/templates
```

**Query parameters:**

| Parameter  | Type   | Description        |
| ---------- | ------ | ------------------ |
| `category` | string | Filter by category |

Returns pre-built workflow templates you can clone using `template_id` in the Create endpoint.

***

## Secrets

Secrets are encrypted key-value pairs available to webhook steps (e.g., API keys for external services).

### List Secrets

```bash theme={"dark"}
GET /api/workflows/secrets
```

Returns secret names (values are never exposed).

### Create Secret

```bash theme={"dark"}
POST /api/workflows/secrets
```

**Body:**

| Field   | Type   | Required | Description                                             |
| ------- | ------ | -------- | ------------------------------------------------------- |
| `name`  | string | Yes      | Secret name (used in step config as `{{secrets.name}}`) |
| `value` | string | Yes      | Secret value (encrypted at rest)                        |

### Delete Secret

```bash theme={"dark"}
DELETE /api/workflows/secrets
```

**Body:**

| Field  | Type   | Required | Description           |
| ------ | ------ | -------- | --------------------- |
| `name` | string | Yes      | Secret name to delete |

***

## Execution Logs

```bash theme={"dark"}
GET /api/workflows/logs?run_id={run_id}
```

Returns detailed execution logs for a specific run, including per-step timing and outputs.

***

## Rate Limits

Workflow runs are rate-limited to **60 runs per minute** per user. Each run has a retry budget of 3 attempts on transient failures.

***

## Credits

Each enrichment step in a workflow consumes credits at the same rate as the corresponding standalone API call. Non-enrichment steps (`condition`, `delay`, `webhook`, `transform`) are free.