Shield API Documentation

Idempotency and execution protection API for workflow safety.

Quick Reference

Base URL:

https://api.ainoflow.io

Authentication:

Authorization: Bearer your_api_key_here

Core Concepts

Lock Key

• Unique identifier for each lock (up to 512 characters)
• Any characters allowed - URL-encode special characters in the path
• Examples: invoice-12345, order:process:789

Token (Lease ID)

• 128-bit cryptographically random token
• Returned in X-Shield-Token header on acquire
• Required for complete and renew operations
• Not required for delete - token is read server-side for audit
• Proves ownership of the lock

Lock Lifecycle

• Locked - Active lock, workflow in progress
• Completed - Workflow finished, TTL extended to 30 days
• Expired - Automatically removed when TTL ends

TTL System

• lock_ttl: Default 30 min, configurable up to 24h
• max_lifetime: 24h absolute deadline from acquire
• completed_ttl: 30 days for duplicate detection
• Renew interval: ~50% of TTL window (every 15 min)

Main Endpoints

POST

Acquire Lock

/api/v1/shield/{key}

Acquire a distributed lock for the given key. Returns 201 if lock acquired, 409 if key already exists (duplicate).

Path Parameters:

key

required

- Unique lock identifier. Max 512 chars. URL-encode special characters.

Query Parameters:

ttl

optional

- Lock TTL in seconds (default: 1800, max: 86400). Capped to max_lifetime

reference

optional

- Reference identifier for audit purposes

returnSuccess

optional

- If true, return 200 OK for duplicates instead of 409 Conflict (default: false)

Response Headers (201 only):

X-Shield-Token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4

Response (201 Created - Lock Acquired):

{
  "key": "invoice-12345",
  "acquired": true,
  "status": "locked",
  "token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "expiresIn": 1800
}

Response (409 Conflict - Duplicate):

{
  "key": "invoice-12345",
  "acquired": false,
  "status": "duplicate",
  "expiresIn": 1800
}

Note: 409 Conflict on acquire is a business response, not an error. Check acquired field to determine next action.

PUT

Complete Lock

/api/v1/shield/{key}/complete

Mark lock as completed. Sets TTL to 30 days for duplicate detection. Idempotent - repeated calls with same token return success.

Request Headers:

X-Shield-Token

required

- Token from acquire operation

Response (200 OK):

{
  "key": "invoice-12345",
  "success": true,
  "status": "completed",
  "expiresIn": 2592000
}

PUT

Renew Lock (Heartbeat)

/api/v1/shield/{key}/renew

Set new lock TTL (heartbeat). The new TTL replaces current TTL but is capped to max_lifetime deadline (24h from acquire).

Query Parameters:

ttl

optional

- New TTL in seconds (default: 1800). Capped to remaining deadline

Request Headers:

X-Shield-Token

required

- Token from acquire operation

Response (200 OK):

{
  "key": "invoice-12345",
  "success": true,
  "expiresIn": 3600
}

Response (200 OK, TTL capped):

{
  "key": "invoice-12345",
  "success": true,
  "expiresIn": 1800,
  "capped": true
}

capped: true indicates requested TTL was reduced to fit within max_lifetime deadline.

GET

Check Lock Status

/api/v1/shield/{key}

Check if lock exists and get remaining TTL. For occasional checks and debugging. Not for high-frequency polling.

Query Parameters:

allowEmpty

optional

- If true, returns empty object {} instead of 404 when lock not found (default: false)

Response (200 OK - exists):

{
  "key": "invoice-12345",
  "exists": true,
  "expiresIn": 2400
}

Response (404 Not Found):

Default when lock is not found. Use allowEmpty=true to get {} (200 OK) instead.

DELETE

Delete Lock

/api/v1/shield/{key}

Delete a lock. For debugging purposes only. Locks are expected to expire automatically. Token is read server-side from storage and used for audit; the X-Shield-Token header is not required.

Response (200 OK):

{
  "key": "invoice-12345",
  "success": true
}

Example Usage

cURL Examples

Acquire lock

curl -X POST "https://api.ainoflow.io/api/v1/shield/invoice-12345?ttl=3600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Complete lock

curl -X PUT "https://api.ainoflow.io/api/v1/shield/invoice-12345/complete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Shield-Token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Renew lock (heartbeat)

curl -X PUT "https://api.ainoflow.io/api/v1/shield/invoice-12345/renew?ttl=3600" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Shield-Token: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4"

Check status

curl "https://api.ainoflow.io/api/v1/shield/invoice-12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

Delete lock (token not required; for debugging only)

curl -X DELETE "https://api.ainoflow.io/api/v1/shield/invoice-12345" \
  -H "Authorization: Bearer YOUR_API_KEY"

n8n / Make.com Integration

Simple Duplicate Check Pattern

Add Shield protection to any workflow in minutes

1. HTTP Request Node (Start):
   POST /api/v1/shield/{{$json.order_id}}
   → Check response status code

2. IF Node:
   Check: $.acquired == true
   
3. True Branch:
   → Process order (your business logic)
   
4. False Branch:
   → Skip (duplicate detected)

5. HTTP Request Node (After processing):
   PUT /api/v1/shield/{{$json.order_id}}/complete
   Header: X-Shield-Token: {{$json.token}}

HTTP Status Codes

200

OK - Request successful (complete, renew, status, delete)

201

Created - Lock acquired successfully

400

Bad Request - Invalid key format, missing token, or invalid parameters

401

Unauthorized - Missing or invalid API key

404

Not Found - Lock not found or expired (complete/renew only)

409

Conflict - On acquire: duplicate detected (business response). On complete/renew: token mismatch or max lifetime exceeded.

500

Internal Server Error - Server error

Best Practices

Key Naming

• Use URL-safe characters only
• Include entity type: invoice:12345
• Be consistent across workflows

TTL Strategy

• Match TTL to workflow duration + buffer
• Renew at ~50% of TTL window
• Always complete when done

Token Handling

• Store token securely during workflow
• Pass via X-Shield-Token header
• Don't log token in plain text

Error Handling

• 409 on acquire = expected duplicate
• Don't retry on 409
• Lock auto-expires if workflow fails

Ready to Get Started?

Create your free account and start protecting your workflows in minutes.

Get API Key Learn More