Skip to main content

​
Workflows API Reference

Programmatically create, deploy, and execute workflows.

​
Base URL

https://api.case.dev/workflows/v1

​
Authentication

All requests require a Bearer token: 
Authorization: Bearer $CASEDEV_API_KEY

​
Create & Deploy Workflow

Create a workflow and deploy it in a single call. Returns a webhook URL and secret.
Endpoint
POST /workflows/v1/create
Request Body:
JSON
{
  "name": "My Workflow",
  "description": "Optional description",
  "nodes": [
    {
      "id": "trigger-1",
      "type": "trigger",
      "label": "Webhook Trigger",
      "config": { "triggerType": "Webhook" }
    },
    {
      "id": "action-1",
      "type": "action",
      "label": "Search Web",
      "config": {
        "actionType": "case-search/web-search",
        "query": "{{topic}}"
      }
    }
  ],
  "edges": [
    { "source": "trigger-1", "target": "action-1" }
  ]
}
Response
{
  "id": "wf_xxx",
  "name": "My Workflow",
  "webhookUrl": "https://api.case.dev/workflows/v1/wf_xxx/webhook",
  "webhookSecret": "whsec_...",
  "status": "deployed",
  "message": "Workflow created and deployed successfully. Save the webhookSecret - it will not be shown again!"
}
Important: The webhookSecret is only returned once. Store it securely.

​
List Workflows

Endpoint
GET /workflows/v1
Returns all workflows for your organization.
Response
{
  "workflows": [
    {
      "id": "wf_xxx",
      "name": "Document Summary",
      "description": "Summarizes documents",
      "status": "deployed",
      "webhookUrl": "https://api.case.dev/workflows/v1/wf_xxx/webhook",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

​
Get Workflow

Endpoint
GET /workflows/v1/{id}
Returns a single workflow with full node/edge configuration.
Response
{
  "id": "wf_xxx",
  "name": "My Workflow",
  "nodes": [...],
  "edges": [...],
  "status": "deployed",
  "webhookUrl": "https://api.case.dev/workflows/v1/wf_xxx/webhook"
}

​
Update Workflow

Endpoint
PATCH /workflows/v1/{id}
Update workflow properties, nodes, or edges. Requires redeployment to take effect.
JSON
{
  "name": "Updated Name",
  "nodes": [...],
  "edges": [...]
}

​
Delete Workflow

Endpoint
DELETE /workflows/v1/{id}
Permanently deletes a workflow and its deployed resources.

​
Deploy Workflow

Endpoint
POST /workflows/v1/{id}/deploy
Deploy or redeploy a workflow. Generates a new webhook secret.
Response
{
  "success": true,
  "webhookUrl": "https://api.case.dev/workflows/v1/wf_xxx/webhook",
  "webhookSecret": "whsec_...",
  "deployedAt": "2024-01-01T00:00:00Z"
}

​
Undeploy Workflow

Endpoint
DELETE /workflows/v1/{id}/deploy
Remove deployed resources. The workflow definition is preserved.

​
Execute via Webhook

Endpoint
POST /workflows/v1/{id}/webhook
Headers:
HeaderRequiredDescription
X-Webhook-SecretYesThe webhook secret from deployment
Content-TypeYesapplication/json
X-Callback-UrlNoURL to receive completion callback
Query Parameters:
ParamDefaultDescription
modeasyncasync (fire-and-forget) or sync (wait for result)
timeout30000Sync mode timeout in milliseconds (max 300000)
Request Body: Any JSON payload—fields are available via {{fieldName}} in templates.
JSON
{
  "topic": "AI legal research",
  "includeNews": true
}
Response (async)
{
  "success": true,
  "executionId": "exec_xxx",
  "status": "RUNNING",
  "message": "Workflow execution started"
}
Response (sync)
{
  "success": true,
  "executionId": "exec_xxx",
  "status": "SUCCEEDED",
  "output": {
    "results": {...}
  }
}

​
Execute (Authenticated)

Endpoint
POST /workflows/v1/{id}/execute
Execute workflow using API key authentication instead of webhook secret. Headers: 
Authorization: Bearer $CASEDEV_API_KEY
JSON
{
  "input": {
    "topic": "AI in legal tech"
  },
  "mode": "sync"
}

​
List Executions

Endpoint
GET /workflows/v1/{id}/runs
Returns execution history for a workflow. Query Parameters:
ParamDefaultDescription
limit50Max results
statusallFilter: RUNNING, SUCCEEDED, FAILED, TIMED_OUT, ABORTED
Response
{
  "executions": [
    {
      "executionArn": "arn:aws:states:...",
      "name": "exec_xxx",
      "status": "SUCCEEDED",
      "startDate": "2024-01-01T12:00:00Z",
      "stopDate": "2024-01-01T12:00:05Z"
    }
  ]
}

​
Get Execution Details

Endpoint
GET /workflows/v1/runs/{executionId}
Returns detailed information about a specific execution including step-by-step logs.
Response
{
  "executionArn": "arn:aws:states:...",
  "status": "SUCCEEDED",
  "input": {...},
  "output": {...},
  "startDate": "2024-01-01T12:00:00Z",
  "stopDate": "2024-01-01T12:00:05Z",
  "events": [
    {
      "id": 1,
      "type": "ExecutionStarted",
      "timestamp": "2024-01-01T12:00:00Z"
    },
    {
      "id": 2,
      "type": "TaskStateEntered",
      "timestamp": "2024-01-01T12:00:01Z",
      "stateEnteredEventDetails": {
        "name": "Search_Web",
        "input": {...}
      }
    }
  ]
}

​
Node Types

​
Trigger Node

Every workflow must have exactly one trigger node.
JSON
{
  "id": "trigger-1",
  "type": "trigger",
  "label": "Webhook Trigger",
  "config": {
    "triggerType": "Webhook"
  }
}

​
Action Node

JSON
{
  "id": "action-1",
  "type": "action",
  "label": "Search Web",
  "config": {
    "actionType": "case-search/web-search",
    "query": "{{topic}}"
  }
}

​
Condition Node

JSON
{
  "id": "condition-1",
  "type": "condition",
  "label": "Check Results",
  "config": {
    "conditionType": "expression",
    "expression": "{{results.Search.output.results.length}} > 0"
  }
}

​
Template Syntax

PatternDescriptionExample
{{fieldName}}Trigger input field{{topic}}
{{results.StepLabel.output}}Previous step output{{results.Search_Web.output}}
{{results.StepLabel.output.field}}Specific field{{results.LLM.output.choices[0].message.content}}
Note: Step labels with spaces become underscores: “Search Web” → Search_Web

​
Error Responses

StatusDescription
400Invalid request (missing fields, invalid JSON)
401Missing or invalid API key / webhook secret
403Insufficient permissions
404Workflow not found
500Internal server error
Response
{
  "error": "Error message",
  "details": "Additional context"
}