REST API Reference

Complete REST API documentation with authentication, endpoints, and WebSocket support

DeepChain REST API Reference

Welcome! This guide covers everything you need to interact with DeepChain's REST API. Whether you're building integrations or automating workflows, you'll find practical examples for every endpoint.

Quick Start

Get up and running in 30 seconds:

# 1. Get your authentication token
curl -X POST https://api.deepchain.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your_password"
  }'

# 2. Copy the accessToken from the response

# 3. Use it to call the API
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.deepchain.dev/api/workflows

Tip: Save your token in an environment variable for easier testing:
export DEEPCHAIN_TOKEN="your_access_token_here"
curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" https://api.deepchain.dev/api/workflows

API Base URLs

Choose the right endpoint for your environment:

Environment	URL
Production	`https://api.deepchain.dev`
Local Development	`http://localhost:8080`
Self-Hosted	`https://your-domain.com`

Authentication Setup

Every API request needs a JWT (JSON Web Token) in the Authorization header.

Getting Your Token

First, trade your email and password for a token:

curl -X POST https://api.deepchain.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your_password"
  }'

You'll get back:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 86400
}

Note: The access token expires in 24 hours. Save the refresh token to get a new one without logging in again.

Using Your Token

Include it in the Authorization header with every request:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  https://api.deepchain.dev/api/workflows

Refreshing Your Token

When your access token expires, use the refresh token to get a new one:

curl -X POST https://api.deepchain.dev/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "YOUR_REFRESH_TOKEN"}'

API Endpoints Overview

Here's a quick reference of all the main endpoints. Click through to the detailed sections below for examples and parameters.

Workflows

Manage your workflow definitions and versions.

Method	Endpoint	What it does
`GET`	`/api/workflows`	List all workflows in your workspace
`POST`	`/api/workflows`	Create a new workflow
`GET`	`/api/workflows/:id`	Get a specific workflow
`PUT`	`/api/workflows/:id`	Update a workflow
`DELETE`	`/api/workflows/:id`	Delete a workflow
`POST`	`/api/workflows/:id/execute`	Run a workflow and get execution ID
`GET`	`/api/workflows/:id/versions`	See all versions of a workflow

Executions

Track workflow runs and their results.

Method	Endpoint	What it does
`GET`	`/api/executions`	List executions with status
`GET`	`/api/executions/:id`	Get results of a specific run
`POST`	`/api/executions/:id/cancel`	Stop a running execution
`POST`	`/api/executions/:id/resume`	Approve and resume a paused workflow
`GET`	`/api/executions/:id/logs`	Get detailed logs from execution

Credentials

Store and manage third-party service credentials securely.

Method	Endpoint	What it does
`GET`	`/api/credentials`	List all your credentials
`POST`	`/api/credentials`	Create new credential (API keys, OAuth tokens, etc.)
`GET`	`/api/credentials/:id`	Get credential details
`PUT`	`/api/credentials/:id`	Update credential
`DELETE`	`/api/credentials/:id`	Delete credential

Workspaces

Organize teams and manage access control.

Method	Endpoint	What it does
`GET`	`/api/workspaces`	List workspaces you have access to
`POST`	`/api/workspaces`	Create a new workspace
`GET`	`/api/workspaces/:id`	Get workspace details
`PUT`	`/api/workspaces/:id`	Update workspace settings
`GET`	`/api/workspaces/:id/members`	List team members
`POST`	`/api/workspaces/:id/members`	Invite someone to the workspace

Workflows API

Workflows are the core of DeepChain. They define the sequence of steps to automate your processes.

List Your Workflows

Get all workflows in your workspace, with optional filtering:

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  "https://api.deepchain.dev/api/workflows?status=active&limit=10"

Query parameters:

Parameter	Type	Example	Purpose
`status`	string	`active`	Filter by `draft`, `active`, or `paused`
`search`	string	`email`	Find workflows by name
`limit`	number	`10`	How many results (default: 50, max: 100)
`offset`	number	`50`	Skip first N results for pagination

Response:

{
  "data": [
    {
      "id": "wf_abc123",
      "name": "Order Processing",
      "description": "Process incoming orders from Shopify",
      "status": "active",
      "createdAt": "2025-01-10T10:00:00Z",
      "updatedAt": "2025-01-11T15:30:00Z"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

Create a New Workflow

Create a workflow from scratch with nodes and connections:

curl -X POST https://api.deepchain.dev/api/workflows \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Simple Email Workflow",
    "description": "Send welcome email to new users",
    "definition": {
      "nodes": [
        {
          "id": "start_1",
          "type": "start",
          "position": {"x": 100, "y": 100}
        },
        {
          "id": "http_1",
          "type": "http_request",
          "position": {"x": 300, "y": 100},
          "config": {
            "url": "https://api.example.com/users",
            "method": "GET"
          }
        },
        {
          "id": "email_1",
          "type": "send_email",
          "position": {"x": 500, "y": 100},
          "config": {
            "subject": "Welcome!",
            "template": "welcome"
          }
        }
      ],
      "connections": [
        {
          "sourceNode": "start_1",
          "sourcePort": "output",
          "targetNode": "http_1",
          "targetPort": "input"
        },
        {
          "sourceNode": "http_1",
          "sourcePort": "output",
          "targetNode": "email_1",
          "targetPort": "input"
        }
      ]
    }
  }'

Execute a Workflow

Trigger a workflow run with input data:

curl -X POST https://api.deepchain.dev/api/workflows/wf_abc123/execute \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "orderId": "ORDER-12345",
      "customerEmail": "john@example.com",
      "priority": "high"
    }
  }'

Response — you get back an execution ID immediately:

{
  "executionId": "exec_xyz789",
  "status": "pending",
  "startedAt": "2025-01-11T10:00:00Z"
}

Note: The workflow runs asynchronously. Use the executionId to check status and results later (see Executions API below).

Get a Workflow

Retrieve the full definition of a workflow:

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  https://api.deepchain.dev/api/workflows/wf_abc123

Update a Workflow

Modify an existing workflow:

curl -X PUT https://api.deepchain.dev/api/workflows/wf_abc123 \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Workflow Name"}'

Delete a Workflow

Remove a workflow (cannot be undone):

curl -X DELETE https://api.deepchain.dev/api/workflows/wf_abc123 \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN"

Warning: Deleted workflows cannot be recovered. Export first if you want a backup.

View Workflow Versions

See the history of changes to a workflow:

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  https://api.deepchain.dev/api/workflows/wf_abc123/versions

Executions API

Monitor and manage workflow runs.

List All Executions

See all runs of your workflows:

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  "https://api.deepchain.dev/api/executions?status=completed&limit=20"

Check Execution Status

Get the result of a workflow run:

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  https://api.deepchain.dev/api/executions/exec_xyz789

Response:

{
  "id": "exec_xyz789",
  "workflowId": "wf_abc123",
  "status": "completed",
  "startedAt": "2025-01-11T10:00:00Z",
  "completedAt": "2025-01-11T10:00:05Z",
  "input": {
    "orderId": "ORDER-12345"
  },
  "output": {
    "result": "success",
    "emailsSent": 1
  },
  "nodeResults": [
    {
      "nodeId": "http_1",
      "status": "completed",
      "startedAt": "2025-01-11T10:00:01Z",
      "completedAt": "2025-01-11T10:00:02Z",
      "output": {
        "statusCode": 200,
        "data": {"userId": "user_123"}
      }
    },
    {
      "nodeId": "email_1",
      "status": "completed",
      "output": {"messageId": "msg_456"}
    }
  ]
}

Status values: pending, running, completed, failed, paused

Cancel a Running Execution

Stop a workflow that's currently running:

curl -X POST https://api.deepchain.dev/api/executions/exec_xyz789/cancel \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN"

Approve and Resume (for workflows with approval steps)

When a workflow pauses at an approval node, resume it with a decision:

curl -X POST https://api.deepchain.dev/api/executions/exec_xyz789/resume \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nodeId": "approval_1",
    "decision": "approved",
    "comment": "All checks passed, proceeding with order"
  }'

Get Execution Logs

See detailed logs from each step:

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  "https://api.deepchain.dev/api/executions/exec_xyz789/logs?nodeId=http_1"

Response:

{
  "logs": [
    {
      "timestamp": "2025-01-11T10:00:01Z",
      "level": "info",
      "message": "HTTP request starting"
    },
    {
      "timestamp": "2025-01-11T10:00:02Z",
      "level": "info",
      "message": "HTTP response received: 200 OK"
    }
  ]
}

Credentials API

Store API keys, OAuth tokens, and other secrets securely to use in your workflows.

Create a Credential

Store connection details for a service:

curl -X POST https://api.deepchain.dev/api/credentials \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salesforce Production",
    "type": "oauth2",
    "connectorId": "salesforce",
    "config": {
      "clientId": "your_salesforce_client_id",
      "clientSecret": "your_salesforce_client_secret",
      "instanceUrl": "https://yourcompany.salesforce.com"
    }
  }'

Response:

{
  "id": "cred_def456",
  "name": "Salesforce Production",
  "type": "oauth2",
  "connectorId": "salesforce",
  "status": "active",
  "createdAt": "2025-01-11T10:00:00Z"
}

Security note: Tokens and secrets are encrypted before storing. We never log or expose the actual secret values.

Common Credential Types

Type	Example	When to use
`api_key`	Stripe, Shopify	Services with a simple API key
`basic_auth`	HTTP Basic Auth	Username + password
`oauth2`	Google, Salesforce	Services that use OAuth 2.0
`custom`	Your own service	Custom authentication schemes

List Your Credentials

See all stored credentials (values are hidden for security):

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  https://api.deepchain.dev/api/credentials

Get a Credential

Retrieve credential details (secret values remain encrypted):

curl -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  https://api.deepchain.dev/api/credentials/cred_def456

Update a Credential

Modify credential settings:

curl -X PUT https://api.deepchain.dev/api/credentials/cred_def456 \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Salesforce Staging"}'

Delete a Credential

Remove a stored credential:

curl -X DELETE https://api.deepchain.dev/api/credentials/cred_def456 \
  -H "Authorization: Bearer $DEEPCHAIN_TOKEN"

Warning: Any workflows using this credential will break. Update them first.

Webhooks

Trigger workflows automatically when external events happen (like an order being placed or a form submitted).

How Webhooks Work

You tell DeepChain to listen on a specific URL
External services send HTTP POST requests to that URL
DeepChain receives the data and runs your workflow
The workflow gets the data as input

Receive Webhook Data

curl -X POST https://api.deepchain.dev/webhooks/wf_abc123/orders \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "data": {
      "orderId": "ORDER-12345",
      "customerEmail": "john@example.com",
      "amount": 99.99
    }
  }'

Response — you get back the execution ID:

{
  "executionId": "exec_xyz789",
  "status": "accepted"
}

Webhook Security with Signatures

DeepChain can verify that webhook requests really came from the service you expect. Every webhook includes a signature:

X-DeepChain-Signature: sha256=abcdef123456789...

To verify the signature in your code:

import 'package:crypto/crypto.dart';

// 1. Get the raw request body (as string, not parsed)
String rawBody = '{"event":"order.created",...}';

// 2. Get the webhook secret (shown when you create the webhook)
String webhookSecret = 'your_webhook_secret';

// 3. Create the expected signature
final expectedSignature = 'sha256=' +
  hmacSha256.convert(
    utf8.encode(rawBody),
    key: utf8.encode(webhookSecret)
  ).toString();

// 4. Compare with the header
String headerSignature = request.headers['X-DeepChain-Signature'] ?? '';
if (expectedSignature != headerSignature) {
  throw Exception('Invalid signature - request is not from DeepChain');
}

Tip: Always verify signatures in production to prevent unauthorized workflow triggers.

Handling Errors

The API uses standard HTTP status codes to indicate success or failure. When something goes wrong, you get a detailed error response.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid workflow definition",
    "details": [
      {
        "field": "nodes[0].type",
        "message": "Unknown node type: invalid_type"
      }
    ]
  }
}

Common Errors & Solutions

HTTP Status	Code	Meaning	How to fix
`400`	`VALIDATION_ERROR`	Your request data is invalid	Check the `details` field for which field is wrong
`401`	`UNAUTHORIZED`	Missing or invalid token	Run login again to get a fresh token
`403`	`FORBIDDEN`	You don't have permission	Contact workspace admin to grant access
`404`	`NOT_FOUND`	The workflow/execution doesn't exist	Double-check the ID, it might have been deleted
`409`	`CONFLICT`	Someone else modified this at the same time	Refresh and try again
`429`	`RATE_LIMITED`	You're sending too many requests	Wait a moment and retry (see Rate Limiting section)
`500`	`INTERNAL_ERROR`	Something broke on our side	Check status page, then contact support if it persists

Retry Strategy

For transient errors (500, 429), implement exponential backoff:

# Attempt 1: wait 1 second
sleep 1
curl ...

# Attempt 2: wait 2 seconds
sleep 2
curl ...

# Attempt 3: wait 4 seconds
sleep 4
curl ...

Note: Idempotent operations (GET, DELETE) are safe to retry. For POST/PUT, include a unique idempotency-key header to prevent duplicate operations.

Rate Limiting

API requests are rate limited per workspace:

Tier	Requests/Minute	Burst
Free	60	100
Starter	300	500
Enterprise	1000	2000

Rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1704974400

WebSocket API (Real-time Updates)

Get live updates as your workflows run, instead of polling.

Connect to WebSocket

const ws = new WebSocket('wss://api.deepchain.dev/ws');

ws.onopen = () => {
  // Authenticate with your token
  ws.send(JSON.stringify({
    type: 'auth',
    token: 'YOUR_ACCESS_TOKEN'
  }));
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};

ws.onclose = () => {
  console.log('Disconnected from DeepChain');
};

Subscribe to Execution Updates

Watch a specific execution as it runs:

ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'execution',
  executionId: 'exec_xyz789'
}));

Receive Live Updates

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  switch (message.type) {
    case 'execution_update':
      console.log(`Status: ${message.status}`);
      console.log(`Current node: ${message.nodeId}`);
      break;

    case 'node_completed':
      console.log(`Node ${message.nodeId} finished`);
      console.log(`Output:`, message.output);
      break;

    case 'execution_completed':
      console.log('Workflow finished!');
      console.log(`Final result:`, message.output);
      break;

    case 'error':
      console.error(`Error: ${message.message}`);
      break;
  }
};

Example messages you'll receive:

{
  "type": "execution_update",
  "status": "running",
  "nodeId": "http_1",
  "timestamp": "2025-01-11T10:00:01Z"
}

{
  "type": "node_completed",
  "nodeId": "http_1",
  "output": {
    "statusCode": 200,
    "data": {"userId": "user_123"}
  }
}

{
  "type": "execution_completed",
  "status": "completed",
  "output": {
    "result": "success",
    "totalTime": "2.5s"
  }
}

Unsubscribe

Stop listening to an execution:

ws.send(JSON.stringify({
  type: 'unsubscribe',
  channel: 'execution',
  executionId: 'exec_xyz789'
}));

Tip: WebSocket connections automatically close after 1 hour of inactivity. Reconnect if needed.

Rate Limiting

To ensure fair use, we rate limit API requests. You'll see remaining requests in every response header.

Plan	Requests/Minute	Burst
Free	60	100
Starter	300	500
Enterprise	1000	2000

Response headers show your current limits:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1704974400

When you hit the limit, you'll get a 429 error. Wait until X-RateLimit-Reset time to try again.

SDK Libraries

Rather than using raw curl/HTTP, try one of our official SDKs:

Dart (for Flutter & backend)

dart pub add deepchain_client

import 'package:deepchain_client/deepchain_client.dart';

final client = DeepChainClient(
  baseUrl: 'https://api.deepchain.dev',
  accessToken: 'your_access_token',
);

// List workflows
final workflows = await client.workflows.list();

// Execute a workflow
final execution = await client.workflows.execute(
  'wf_abc123',
  input: {'orderId': 'ORDER-12345'},
);

// Wait for it to finish
final result = await client.executions.waitForCompletion(
  execution.id,
  timeout: Duration(minutes: 5),
);

print('Result: ${result.output}');

JavaScript/TypeScript

npm install @deepchain/client

import { DeepChainClient } from '@deepchain/client';

const client = new DeepChainClient({
  baseUrl: 'https://api.deepchain.dev',
  accessToken: 'your_access_token'
});

// List workflows
const workflows = await client.workflows.list();

// Execute workflow
const execution = await client.workflows.execute('wf_abc123', {
  orderId: 'ORDER-12345'
});

// Poll for completion
const result = await client.executions.waitForCompletion(execution.id);
console.log(result.output);

Python

pip install deepchain-client

from deepchain import DeepChainClient

client = DeepChainClient(
    base_url='https://api.deepchain.dev',
    access_token='your_access_token'
)

# List workflows
workflows = client.workflows.list()

# Execute workflow
execution = client.workflows.execute(
    'wf_abc123',
    input={'orderId': 'ORDER-12345'}
)

# Wait for completion
result = client.executions.wait_for_completion(
    execution.id,
    timeout=300  # 5 minutes
)
print(result.output)

API Testing Tools

Postman Collection

Import our Postman collection to test APIs in the GUI:

📥 Download Postman Collection

OpenAPI Specification

Full OpenAPI 3.0 spec for integration with your tools:

https://api.deepchain.dev/openapi.json  (JSON format)
https://api.deepchain.dev/openapi.yaml  (YAML format)

Next Steps

Getting Started: Build your first workflow
SDK Docs: Create custom nodes
CLI Reference: Command-line tools
Deployment: Deploy to production