xEvolve API Documentation

xEvolve API

Use the xEvolve REST API to integrate secure file transfers into your applications. Connect any storage system, automate transfers, and receive real-time event notifications.

Base URL

https://xevolve-api-dev.reactor-servers.workers.dev/api/v1

11 Protocols

S3, R2, GCS, Azure Blob, SFTP, FTP, SMB, NFS, WebDAV, OneDrive, Azure File Share

Transfer Engine

Queue, execute, and track file transfers between any two storage endpoints

Scoped API Keys

Fine-grained permissions with xev_ prefixed keys and SHA-256 hashed storage

Webhooks

Real-time notifications with HMAC-SHA256 signed payloads for all events

Audit Trail

Every action logged — uploads, downloads, transfers, access events

Edge-Native

Runs on Cloudflare Workers. Low latency from 300+ locations worldwide

Response Format

All responses return JSON. Successful responses include a data field. Error responses include an error string with a descriptive message.

{ "data": { ... } }

{ "error": "Descriptive message" }

Authentication

Authenticate API requests using Bearer tokens. xEvolve supports two methods: API keys (recommended for integrations) and JWT session tokens (for browser sessions).

API Key Authentication

Generate API keys from the xEvolve dashboard under Profile > API Keys. Keys use the xev_ prefix and are SHA-256 hashed at rest. The full key is shown only once at creation.

bash

curl -X GET "https://api.xevolve.io/api/v1/transfers" \
  -H "Authorization: Bearer xev_your_api_key_here"

Scoped Permissions

Each API key has a set of scopes that control access. Requests to endpoints requiring a scope the key doesn't have return 403.

Resource	Scope	Description
Files	`files:read`	List, search, and download files
Files	`files:write`	Upload and delete files
Transfers	`transfers:read`	List and view transfer jobs
Transfers	`transfers:write`	Create, execute, cancel, and delete transfers
Connections	`connections:read`	List storage connections
Connections	`connections:write`	Create, update, delete, and test connections
Data Rooms	`data-rooms:read`	List and view data rooms
Data Rooms	`data-rooms:write`	Create and manage data rooms
Schedules	`schedules:read`	List scheduled transfers
Schedules	`schedules:write`	Create and manage schedules
Watchers	`watchers:read`	List file watchers
Watchers	`watchers:write`	Create and manage watchers
Workflows	`workflows:read`	List workflows
Workflows	`workflows:write`	Create and manage workflows

Connections

Connections represent storage endpoints. Create connections to configure source and destination endpoints for file transfers.

s3r2gcsblobfilesharesftpftpsmbnfswebdavonedrive

GET/api/v1/connectionsconnections:read

List all connections for the authenticated user.

POST/api/v1/connectionsconnections:write

Create a new storage connection. Credentials are AES-encrypted at rest.

json

{
  "name": "Production S3",
  "type": "s3",
  "host": "s3.amazonaws.com",
  "port": 443,
  "path": "/my-bucket",
  "credentials": {
    "access_key_id": "AKIA...",
    "secret_access_key": "..."
  }
}

GET/api/v1/connections/:idconnections:read

Get a single connection by ID. Credentials are never returned.

PUT/api/v1/connections/:idconnections:write

Update a connection. Only provided fields are changed.

DELETE/api/v1/connections/:idconnections:write

Delete a connection permanently.

POST/api/v1/connections/:id/testconnections:write

Test connectivity to the storage endpoint. Returns success status and message.

Credential Fields by Type

Type	Credential Fields
s3, r2, gcs	access_key_id, secret_access_key, region (optional)
blob, fileshare	connection_string or account_name + account_key
sftp	username, password or private_key
ftp	username, password
smb	username, password, domain (optional)
webdav	username, password
onedrive	client_id, client_secret, tenant_id, refresh_token

Transfers

Transfers move files between two connections. Create a transfer job, then execute it. Track progress via the job status and poll for completion.

Transfer Lifecycle

queued→in-progress→completed|failedcancelled

GET/api/v1/transferstransfers:read

List transfer jobs. Supports ?status= filter (queued, in-progress, completed, failed, cancelled).

POST/api/v1/transferstransfers:write

Create a new transfer job. The job is created in 'queued' status.

json

{
  "name": "Daily Backup",
  "sourceConnectionId": "conn_abc123",
  "sourcePath": "/data/exports",
  "destinationConnectionId": "conn_def456",
  "destinationPath": "/backups/2025-03"
}

GET/api/v1/transfers/:idtransfers:read

Get transfer job details including progress (files_total, files_transferred, bytes_transferred).

POST/api/v1/transfers/:id/executetransfers:write

Execute a queued transfer. Streams files from source to destination. Returns transfer summary on completion.

json

// Response
{
  "success": true,
  "files_transferred": 42,
  "bytes_transferred": 15728640
}

POST/api/v1/transfers/:id/canceltransfers:write

Cancel a queued or in-progress transfer.

DELETE/api/v1/transfers/:idtransfers:write

Delete a completed, failed, or cancelled transfer job.

Transfer Job Fields

Field	Description
status	queued, in-progress, completed, failed, cancelled
files_total	Total files found in source path
files_transferred	Files successfully copied (updated every 5 files)
bytes_transferred	Total bytes moved
started_at	When execution began
completed_at	When execution finished
error	Error message if status is failed

Files

Upload, download, search, and share files stored in xEvolve's R2 storage. All uploads are scanned for malware before storage.

GET/api/v1/filesfiles:read

List files for the authenticated user. Supports ?path= filter (default: '/').

POST/api/v1/files/uploadfiles:write

Upload a file via multipart form data. Files are virus-scanned before storage.

bash

curl -X POST "https://api.xevolve.io/api/v1/files/upload" \
  -H "Authorization: Bearer xev_your_key" \
  -F "file=@report.pdf" \
  -F "path=/reports/2025"

GET/api/v1/files/:id/downloadfiles:read

Download a file by ID. Returns the file as a binary stream with appropriate Content-Type.

DELETE/api/v1/files/:idfiles:write

Soft-delete a file. The file is marked as deleted but retained for audit purposes.

GET/api/v1/files/searchfiles:read

Search files by name, type, or size. Supports ?q=, ?type=, ?min_size=, ?max_size= parameters.

bash

# Search by name
curl "https://api.xevolve.io/api/v1/files/search?q=report" \
  -H "Authorization: Bearer xev_your_key"

# Filter by MIME type and size
curl "https://api.xevolve.io/api/v1/files/search?type=application/pdf&min_size=1024" \
  -H "Authorization: Bearer xev_your_key"

POST/api/v1/files/:id/sharefiles:write

Create a shareable download link. Supports expiration and download limits.

json

// Request
{
  "expires_in_hours": 24,
  "max_downloads": 5
}

// Response
{
  "data": {
    "id": "share_abc123",
    "token": "unique-share-token",
    "expires_at": "2025-03-12T10:00:00Z",
    "max_downloads": 5,
    "url": "/api/v1/files/shared/unique-share-token"
  }
}

GET/api/v1/files/shared/:token

Download a shared file. No authentication required. Respects expiration and download limits.

Returns 410 Gone if the link has expired or the download limit has been reached.

Webhooks

Receive real-time HTTP notifications when events occur. Payloads are signed with HMAC-SHA256 so you can verify authenticity.

GET/api/v1/webhooks

List all registered webhooks.

POST/api/v1/webhooks

json

{
  "url": "https://your-app.com/webhooks/xevolve",
  "events": ["transfer.completed", "transfer.failed"],
  "secret": "optional-custom-secret"
}

PUT/api/v1/webhooks/:id

Update webhook URL, events, or active status.

DELETE/api/v1/webhooks/:id

Delete a webhook.

POST/api/v1/webhooks/:id/test

Send a test event to verify delivery.

Event Types

Files

file.uploadedfile.downloadedfile.deletedfile.sharedfile.scan_blocked

Transfers

transfer.startedtransfer.completedtransfer.failed

Data Rooms

data_room.createddata_room.file_addeddata_room.member_added

Users

user.loginuser.registered

Verifying Signatures

Each webhook delivery includes an X-Webhook-Signature header and X-Webhook-Event header. Verify the signature by computing HMAC-SHA256 of the raw body with your webhook secret.

typescript

import crypto from 'crypto'

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  )
}

// In your webhook handler
app.post('/webhooks/xevolve', (req, res) => {
  const signature = req.headers['x-webhook-signature']
  const event = req.headers['x-webhook-event']
  const body = JSON.stringify(req.body)

  if (!verifyWebhook(body, signature, process.env.XEVOLVE_WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature')
  }

  // Process the event
  console.log(`Event: ${event}`, req.body.data)
  res.status(200).send('OK')
})

Payload Format

json

{
  "event": "transfer.completed",
  "timestamp": "2025-03-11T15:30:00.000Z",
  "data": {
    "id": "transfer_abc123",
    "files_transferred": 42,
    "bytes_transferred": 15728640
  }
}

API Keys

Manage API keys programmatically. Keys are generated with the xev_ prefix and stored as SHA-256 hashes. The full key is returned only once at creation.

GET/api/v1/api-keys

List all API keys for the authenticated user. The full key is never returned — only the prefix (e.g., xev_a1b2c3d4...).

POST/api/v1/api-keys

Create a new API key with specified scopes and optional expiration.

json

// Request
{
  "name": "CI/CD Pipeline",
  "scopes": ["transfers:read", "transfers:write", "connections:read"],
  "expires_in_days": 90
}

// Response (key shown ONLY here — save it now)
{
  "data": {
    "id": "key_abc123",
    "name": "CI/CD Pipeline",
    "key": "xev_a1b2c3d4e5f6...",
    "key_prefix": "xev_a1b2c3d4...",
    "scopes": ["transfers:read", "transfers:write", "connections:read"],
    "expires_at": "2025-06-09T00:00:00Z"
  },
  "warning": "Save this API key now. It cannot be shown again."
}

DELETE/api/v1/api-keys/:id

Revoke an API key immediately. All future requests with this key will return 401.

Security Best Practices

Use the minimum scopes needed for your integration
Set expiration dates — rotate keys regularly
Store keys in environment variables, never in code
Revoke keys immediately if compromised
Use separate keys for different environments (dev, staging, prod)

Quick Start

Get up and running with the xEvolve API in minutes. This guide shows how to create connections, run a transfer, and receive webhook notifications.

Create an API Key

Go to your xEvolve dashboard → Profile → API Keys and create a key with transfers:write and connections:write scopes.

Create Source & Destination Connections

bash

# Create an S3 source
curl -X POST "https://api.xevolve.io/api/v1/connections" \
  -H "Authorization: Bearer xev_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS Production",
    "type": "s3",
    "host": "s3.us-east-1.amazonaws.com",
    "path": "/my-bucket",
    "credentials": {
      "access_key_id": "AKIA...",
      "secret_access_key": "...",
      "region": "us-east-1"
    }
  }'

# Create an SFTP destination
curl -X POST "https://api.xevolve.io/api/v1/connections" \
  -H "Authorization: Bearer xev_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner SFTP",
    "type": "sftp",
    "host": "sftp.partner.com",
    "port": 22,
    "path": "/incoming",
    "credentials": {
      "username": "xevolve",
      "private_key": "-----BEGIN RSA..."
    }
  }'

Create & Execute a Transfer

bash

# Create the transfer job
TRANSFER=$(curl -s -X POST "https://api.xevolve.io/api/v1/transfers" \
  -H "Authorization: Bearer xev_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Export",
    "sourceConnectionId": "SOURCE_CONN_ID",
    "sourcePath": "/exports/today",
    "destinationConnectionId": "DEST_CONN_ID",
    "destinationPath": "/incoming/today"
  }')

TRANSFER_ID=$(echo $TRANSFER | jq -r '.id')

# Execute it
curl -X POST "https://api.xevolve.io/api/v1/transfers/$TRANSFER_ID/execute" \
  -H "Authorization: Bearer xev_your_key"

# Check status
curl "https://api.xevolve.io/api/v1/transfers/$TRANSFER_ID" \
  -H "Authorization: Bearer xev_your_key" | jq '.status'

Set Up a Webhook (Optional)

bash

curl -X POST "https://api.xevolve.io/api/v1/webhooks" \
  -H "Authorization: Bearer xev_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/xevolve",
    "events": ["transfer.completed", "transfer.failed"]
  }'

Rate Limits

The API is rate-limited per account. If you receive a 429 response, wait and retry with exponential backoff. Contact support if you need higher limits.

Health Check

bash

curl "https://api.xevolve.io/api/v1/health"
# Returns: { "status": "ok" }