CoreNova Docs / Office Format Conversion API / Quick start

First successful conversion

Convert a legacy Office file in two API operations

Use the CoreNova API key created after AWS Marketplace registration. Keep it server-side. The examples below submit one file, poll the task, and download the modern OOXML result.

Prerequisites

• An active Starter, Team, or Business AWS Marketplace entitlement.
• A CoreNova API key beginning with cnfc_.
• One valid Office 97-2003 file no larger than 4 MiB.

If you do not have a key, follow Purchase and API Key Setup.

cURL

1. Submit the file

export CORENOVA_API_KEY='cnfc_REPLACE_WITH_YOUR_KEY'

curl --request POST 'https://api.corenovacloud.com/v1/conversions' \
  --header "Authorization: Bearer ${CORENOVA_API_KEY}" \
  --header 'Idempotency-Key: archive-batch-42-file-1' \
  --form 'file=@example.doc'

The API accepts the upload and returns HTTP 202:

{
  "task_id": "7bf1fb66240f4a99ad7786b0ed8b2a34",
  "status": "QUEUED",
  "status_url": "https://api.corenovacloud.com/v1/conversions/7bf1fb66240f4a99ad7786b0ed8b2a34",
  "idempotent_replay": false
}

2. Query the task

curl --header "Authorization: Bearer ${CORENOVA_API_KEY}" \
  'https://api.corenovacloud.com/v1/conversions/7bf1fb66240f4a99ad7786b0ed8b2a34'

Continue querying while the state is QUEUED or PROCESSING. On success:

{
  "task_id": "7bf1fb66240f4a99ad7786b0ed8b2a34",
  "status": "SUCCEEDED",
  "source_filename": "example.doc",
  "billing_class": "INCLUDED",
  "result_size": 17030,
  "download_url": "https://temporary-download-url.example/...",
  "download_expires_in": 300
}

3. Download the result

curl --output example.docx 'DOWNLOAD_URL_FROM_TASK_RESPONSE'

The download URL lasts five minutes. If it expires while the result remains within its approximately 30-minute retention window, query the task again for a fresh URL.

4. Check plan usage

curl --header "Authorization: Bearer ${CORENOVA_API_KEY}" \
  'https://api.corenovacloud.com/v1/account/usage'

The endpoint reports shared DOC/PPT/XLS allowance. billing_class is INCLUDED while allowance remains and OVERAGE after it is exhausted.

Python example

import os
import time
from pathlib import Path

import requests

BASE_URL = "https://api.corenovacloud.com"
API_KEY = os.environ["CORENOVA_API_KEY"]
source = Path("example.doc")
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": "archive-batch-42-file-1",
}

with source.open("rb") as handle:
    submitted = requests.post(
        f"{BASE_URL}/v1/conversions",
        headers=headers,
        files={"file": (source.name, handle, "application/octet-stream")},
        timeout=30,
    )
submitted.raise_for_status()
task = submitted.json()

while True:
    status = requests.get(
        f"{BASE_URL}/v1/conversions/{task['task_id']}",
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=15,
    )
    status.raise_for_status()
    task = status.json()
    if task["status"] == "SUCCEEDED":
        result = requests.get(task["download_url"], timeout=30)
        result.raise_for_status()
        Path("example.docx").write_bytes(result.content)
        break
    if task["status"] in {"FAILED", "EXPIRED"}:
        raise RuntimeError(task)
    time.sleep(2)

Node.js 20 example

import { openAsBlob } from "node:fs";
import { writeFile } from "node:fs/promises";

const baseUrl = "https://api.corenovacloud.com";
const apiKey = process.env.CORENOVA_API_KEY;
const form = new FormData();
form.set("file", await openAsBlob("example.doc"), "example.doc");

let response = await fetch(`${baseUrl}/v1/conversions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Idempotency-Key": "archive-batch-42-file-1",
  },
  body: form,
});
if (!response.ok) throw new Error(await response.text());
let task = await response.json();

while (true) {
  response = await fetch(`${baseUrl}/v1/conversions/${task.task_id}`, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  if (!response.ok) throw new Error(await response.text());
  task = await response.json();
  if (task.status === "SUCCEEDED") {
    const result = await fetch(task.download_url);
    await writeFile("example.docx", Buffer.from(await result.arrayBuffer()));
    break;
  }
  if (["FAILED", "EXPIRED"].includes(task.status)) throw new Error(JSON.stringify(task));
  await new Promise((resolve) => setTimeout(resolve, 2000));
}

Retry safely

Use a unique Idempotency-Key for each source file. Repeating the identical upload with the same key returns the original task and does not consume allowance twice. Reusing the key with different bytes returns idempotency_conflict.

Production checklist

• Load the API key from a server-side secret manager.
• Use a stable idempotency key derived from your internal job or file identifier.
• Back off between task queries; a two- to five-second interval is sufficient for ordinary jobs.
• Handle all terminal states and stable error codes.
• Download the result promptly and verify business-critical output.
• Do not log the bearer key or temporary download URL.