SDK & Integration

TokenFlow integrates with agent frameworks and works with any HTTP client.

OpenClaw

Install the skill:

openclaw skills install tokenflow

Or manually copy to ~/.openclaw/skills/tokenflow/.

Configure in ~/.openclaw/skills/tokenflow/config.json:

{
  "apiKey": "your-api-key",
  "apiUrl": "https://tokenflow.fly.dev",
  "filetypeBehavior": {
    "docx": { "action": "convert", "askEachTime": false },
    "pdf":  { "action": "convert", "askEachTime": false },
    "xlsx": { "action": "convert", "askEachTime": true }
  },
  "outputFormat": "markdown",
  "maxRetries": 1,
  "fallbackBehavior": "use_file"
}

When a user attaches a supported file, OpenClaw automatically calls TokenFlow based on filetypeBehavior rules.

Hermes

Copy the skill directory to ~/.hermes/skills/tokenflow/.

Configure in ~/.hermes/skills/tokenflow/config.json (same schema as OpenClaw).

Hermes agents load the skill automatically on startup if present in the skills directory.

JavaScript / Node.js

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

async function convertFile(filePath, apiKey) {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath));
  form.append('output_format', 'markdown');

  const response = await fetch('https://tokenflow.fly.dev/convert', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      ...form.getHeaders()
    },
    body: form
  });

  const data = await response.json();
  // For ZIP archives, data.type === 'zip' and data.results is an array
  if (data.type === 'zip') {
    return data.results.filter(r => r.status === 'success').map(r => r.markdown).join('\n\n');
  }
  return data.markdown;
}

Python

import requests

def convert_file(file_path, api_key, output_format="markdown"):
    url = "https://tokenflow.fly.dev/convert"
    headers = {"Authorization": f"Bearer {api_key}"}

    with open(file_path, "rb") as f:
        files = {"file": f}
        data = {"output_format": output_format}
        response = requests.post(url, headers=headers, files=files, data=data)

    response.raise_for_status()
    return response.json()["markdown"]

# Convert a URL
def convert_url(target_url, api_key):
    url = "https://tokenflow.fly.dev/convert/url"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    response = requests.post(url, headers=headers, json={"url": target_url})
    response.raise_for_status()
    return response.json()["markdown"]

cURL Examples

Convert a PDF:

curl -X POST "https://tokenflow.fly.dev/convert" \
  -H "Authorization: Bearer ${TOKENFLOW_API_KEY}" \
  -F "file=@report.pdf" \
  -F "output_format=markdown"

Convert a URL:

curl -X POST "https://tokenflow.fly.dev/convert/url" \
  -H "Authorization: Bearer ${TOKENFLOW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Preview XLSX sheets:

curl -X POST "https://tokenflow.fly.dev/convert/preview" \
  -H "Authorization: Bearer ${TOKENFLOW_API_KEY}" \
  -F "file=@data.xlsx"

Check usage:

curl -H "Authorization: Bearer ${TOKENFLOW_API_KEY}" \
  "https://tokenflow.fly.dev/usage"