Developer access

WonderConvert API

Submit conversion jobs, check tracked outputs, and review workspace usage through a Pro-only API designed for practical early integrations.

Discuss API access Discuss your use case

Read limit 20/min

Per active API key on the current workspace plan.

Write limit 5/min

Job submission ceiling for the current workspace plan.

Active keys 0/0

Manual API key issuance is tied to approved Pro workspaces.

API access Pro only

Authentication uses `X-API-Key` or `Authorization: Bearer`.

How it works

Manual approval today, cleaner self-serve later

Tell us about your integration and the conversion volume you expect.
We review the use case and manually approve early API access when it fits.
Use the API to submit jobs and poll for outputs.

Available endpoints

Current API surface

POST /api/v1/jobs submits a tracked conversion job.
GET /api/v1/jobs/{requestId} returns job state and download links.
GET /api/v1/usage returns workspace and API-specific usage.

Integration flow

Typical integration path

Submit a job with `POST /api/v1/jobs` using an API key and optional `Idempotency-Key`.
Store the returned `request_id` and `job_status_url` in your own system.
Either poll `GET /api/v1/jobs/{requestId}` or accept webhook callbacks for terminal states.
Download outputs before retention expires, or persist them into your own storage immediately.

Error model

Current response shape

`202` for accepted job creation.
`200` for idempotent replay of an existing job.
`401` for missing or invalid API key.
`403` for missing scope or API access on the workspace plan.
`422` for invalid conversion parameters or file validation failure.
`429` for workspace quota limits.

Quickstart

Submit a conversion job

Use multipart form data with an API key tied to an approved Pro workspace.

curl -X POST "https://wonderconvert.com/api/v1/jobs" \
  -H "X-API-Key: wc_your_key_here" \
  -H "Idempotency-Key: invoice-2026-03-12-run-001" \
  -F "conversion_type=image" \
  -F "from=png" \
  -F "to=jpg" \
  -F "webhook_url=https://client.example/webhooks/wonderconvert" \
  -F "webhook_secret=client_shared_secret" \
  -F "total_files=1" \
  -F "total_size=0.25" \
  -F "files[][email protected]"

Create response

What job submission returns

{
  "status": 202,
  "message": "Your files are being processed.",
  "job_id": 481,
  "request_id": "req_xxxxx",
  "job_status_url": "https://wonderconvert.com/api/v1/jobs/req_xxxxx"
}

Status response

What a completed job looks like

{
  "status": 200,
  "workspace": {
    "slug": "api-workspace"
  },
  "job": {
    "request_id": "req_xxxxx",
    "status": "completed",
    "conversion_type": "image",
    "source_format": "png",
    "target_format": "jpg"
  },
  "outputs": [
    {
      "file_name": "output.jpg",
      "download_url": "https://..."
    }
  ]
}

Status retrieval

Poll the job endpoint for outputs

curl "https://wonderconvert.com/api/v1/jobs/req_xxxxx" \
  -H "Authorization: Bearer wc_your_key_here"

The response includes status, conversion metadata, and time-limited download URLs for completed outputs.

Usage reporting

Track API activity separately from browser usage

curl "https://wonderconvert.com/api/v1/usage" \
  -H "X-API-Key: wc_your_key_here"

The usage response now includes both total workspace activity and API-only usage, plus lifecycle counts for submitted, pending, processing, completed, and failed API jobs.

Node example

Minimal polling integration in JavaScript

This is the simplest safe pattern if you do not want to rely on webhooks yet.

const apiKey = process.env.WONDERCONVERT_API_KEY;

async function submitAndPoll(formData) {
  const createResponse = await fetch("https://wonderconvert.com/api/v1/jobs", {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "Idempotency-Key": `job-${Date.now()}`
    },
    body: formData
  });

  const created = await createResponse.json();
  let statusUrl = created.job_status_url;

  while (true) {
    const statusResponse = await fetch(statusUrl, {
      headers: { "X-API-Key": apiKey }
    });
    const status = await statusResponse.json();

    if (status.job.status === "completed") return status.outputs;
    if (status.job.status === "failed") throw new Error(status.job.error_message);

    await new Promise(resolve => setTimeout(resolve, 3000));
  }
}

Webhook delivery

Receive job completion and failure callbacks

Include `webhook_url` and optionally `webhook_secret` on job submission. WonderConvert sends signed JSON payloads with `X-WonderConvert-Event`, `X-WonderConvert-Request-Id`, and `X-WonderConvert-Signature` headers.

{
  "event": "conversion.job.completed",
  "workspace": {
    "slug": "api-workspace"
  },
  "job": {
    "request_id": "req_xxxxx",
    "status": "completed",
    "idempotency_key": "invoice-2026-03-12-run-001"
  },
  "outputs": [
    {
      "file_name": "output.jpg",
      "download_url": "https://..."
    }
  ]
}

Signature verification

Verify callbacks with your shared secret

$rawBody = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $sharedSecret);
$received = $_SERVER['HTTP_X_WONDERCONVERT_SIGNATURE'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit('Invalid signature');
}

This lets you trust that the webhook payload came from WonderConvert and was not modified in transit.

Recovery workflow

Replay failed webhooks when a client endpoint recovers

php artisan api:replay-job-webhook req_xxxxx

# Optional event override
php artisan api:replay-job-webhook req_xxxxx \
  --event=conversion.job.completed

# Batch replay recent failed webhook jobs
php artisan api:replay-failed-webhooks --limit=25

Webhook delivery state, retry timing, attempt history, and the last delivery error are visible on the job detail page inside the dashboard.

Launch checklist

Before you ship an integration

Use `Idempotency-Key` for every job creation request that can be retried.
Persist the returned `request_id` in your own database.
Verify webhook signatures if you expose a public callback endpoint.
Download outputs quickly or copy them into your own storage.
Monitor `GET /api/v1/usage` so workspace limits do not surprise you.

Current constraints

What to expect from the current beta posture

API keys are issued manually, not self-serve yet.
The queue and webhook system are production-minded, but still part of an early-stage rollout.
There is no customer-facing webhook history screen yet outside the job detail workflow.
Broad API launch is intentionally delayed until infrastructure hardening is complete.

Operational notes

What to expect in the current phase

API keys are issued manually today, which fits the current manual Pro rollout.
Jobs run through the same async pipeline as browser conversions, so job state and retention behave consistently.
Use the `Idempotency-Key` header on job creation if your integration may retry requests after timeouts or network failures.
Webhook payloads can be verified with the `X-WonderConvert-Signature` header when you pass a `webhook_secret` on submission.
Webhook delivery retries automatically on the queue, and manual replay is available through an Artisan command for recovery work.
API access is intentionally conservative until production queue rollout and infra hardening are fully complete.