API Reference

Authorization: Bearer cvfly_sk_live_abc123def456...

curl -X POST https://convertfly.io/api/v1/jobs \
  -H "Authorization: Bearer cvfly_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "invoice-batch",
    "tasks": {
      "import-file": {
        "operation": "import/url",
        "url": "https://example.com/invoice.pdf"
      },
      "to-png": {
        "operation": "convert",
        "input": ["import-file"],
        "output_format": "png",
        "options": { "density": 300 }
      },
      "export": {
        "operation": "export/url",
        "input": ["to-png"]
      }
    }
  }'

{
  "data": {
    "id": "job_7kX9mP2qR",
    "tag": "invoice-batch",
    "status": "PROCESSING",
    "credits_used": 1,
    "created_at": "2026-04-03T10:30:00Z",
    "tasks": {
      "import-file": { "status": "FINISHED" },
      "to-png":      { "status": "PROCESSING" },
      "export":      { "status": "WAITING" }
    }
  }
}

curl https://convertfly.io/api/v1/jobs/job_7kX9mP2qR \
  -H "Authorization: Bearer cvfly_sk_..."

curl "https://convertfly.io/api/v1/jobs?status=FINISHED&limit=5" \
  -H "Authorization: Bearer cvfly_sk_..."

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 5,
    "total": 42
  }
}

curl -X DELETE https://convertfly.io/api/v1/jobs/job_7kX9mP2qR \
  -H "Authorization: Bearer cvfly_sk_..."

curl "https://convertfly.io/api/v1/jobs/job_7kX9mP2qR/wait?timeout=120" \
  -H "Authorization: Bearer cvfly_sk_..."

{
  "data": [
    {
      "name": "import-file",
      "operation": "import/url",
      "status": "FINISHED",
      "result": { "file_id": "file_Xk9m..." }
    },
    {
      "name": "convert",
      "operation": "convert",
      "status": "FINISHED",
      "result": { "file_id": "file_Pm3n..." }
    }
  ]
}

{
  "import-file": {
    "operation": "import/url",
    "url": "https://example.com/document.pdf",
    "filename": "document.pdf",
    "headers": {
      "Authorization": "Bearer your-external-token"
    }
  }
}

{
  "upload-file": {
    "operation": "import/upload",
    "filename": "photo.jpg"
  }
}

# The task result will contain the presigned URL
curl -X PUT "https://storage.convertfly.io/upload/abc123..." \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

{
  "import-file": {
    "operation": "import/base64",
    "file": "JVBERi0xLjQKJcOkw7zD...",
    "filename": "document.pdf"
  }
}

{
  "convert-hq": {
    "operation": "convert",
    "input": ["import-file"],
    "output_format": "png",
    "options": {
      "density": 300,
      "quality": 95
    }
  }
}

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

{
  "data": {
    "id": "wh_Abc123...",
    "url": "https://your-app.com/webhooks/convertfly",
    "events": ["job.finished", "job.failed"],
    "signing_secret": "whsec_9f8e7d6c5b4a...",
    "created_at": "2026-04-03T10:30:00Z"
  }
}

{
  "event": "job.finished",
  "timestamp": "2026-04-03T10:31:15Z",
  "data": {
    "id": "job_7kX9mP2qR",
    "status": "FINISHED",
    "tasks": { ... }
  }
}

import crypto from "crypto";

function verifyWebhook(rawBody, signature, timestamp, secret) {
  const signedContent = timestamp + "." + rawBody;
  const expected = "v1=" + crypto
    .createHmac("sha256", secret)
    .update(signedContent)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

import hmac, hashlib

def verify_webhook(raw_body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    signed_content = f"{timestamp}.{raw_body.decode()}"
    expected = "v1=" + hmac.new(
        secret.encode(), signed_content.encode(), hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

{
  "data": {
    "id": "key_Xk9m...",
    "name": "production-server",
    "key": "cvfly_sk_live_abc123def456...",
    "scopes": ["*"],
    "created_at": "2026-04-03T10:30:00Z"
  }
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743681600
Retry-After: 45

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Rate limit exceeded. Retry after 45 seconds."
}

{
  "code": "INVALID_DATA",
  "message": "Missing required field: output_format",
  "details": {
    "field": "output_format",
    "reason": "required"
  }
}

const res = await fetch("https://convertfly.io/api/v1/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer cvfly_sk_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ tasks: { /* ... */ } }),
});

if (!res.ok) {
  const error = await res.json();
  console.error(`[${error.code}] ${error.message}`);
  // "[INVALID_DATA] Missing required field: output_format"
  return;
}

const { data: job } = await res.json();

HTTP/1.1 201 Created
Content-Type: application/json
X-Credits-Remaining: 9847
X-Credits-Used: 2