TypeScript client

@reviseio/api is a public package for Node.js 22+ or compatible runtimes with native fetch, FormData, Blob, Web Crypto, and AbortSignal.any. It has no runtime npm dependencies. Use it on your server. API keys must stay out of browser bundles.

npm install @reviseio/api

Edit and convert

edit(source, prompt, options) and convert(source, format, options) resolve input, upload when needed, submit the job, and poll. Both return a Source whose output bytes download only when requested.

import { ReviseClient, Source } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const edited = await revise.edit(
  Source.fromPath("contract.docx"),
  "Change the payment term to 30 days.",
  { idempotencyKey: "contract-42-edit" },
);
const pdf = await revise.convert(edited, "pdf", {
  idempotencyKey: "contract-42-pdf",
});
await pdf.save("contract.pdf", { signal: AbortSignal.timeout(60_000) });

Edits select the clean DOCX by default. Set trackedChanges: true to select tracked output, or use edited.variant("tracked_changes") to access it from the same job. This changes output selection, not whether revisions are recorded. source.result contains the receipt; check prompt incomplete and stop_reason. source.artifact contains selected output metadata. An eligible artifact passes directly into another edit. Converting an artifact downloads and reuploads it because conversions require file IDs. Edits requesting output encryption also reupload plaintext artifact inputs. Encrypted artifacts must be decrypted locally before reuse. Every reupload remains subject to the 18 MiB input limit.

Create a Source

Factory	Input
`Source.fromBytes(bytes, { filename })`	Uint8Array, Buffer, or ArrayBuffer.
`Source.fromPath(path, options?)`	Local file, read lazily; Node only.
`Source.fromUrl(url, options?)`	HTTP(S) URL; optional source-specific `headers` and `fetch`.
`Source.fromBlob(blob, options?)`	Blob or File; a File supplies its name.
`Source.fromStream(streamOrFactory, { filename })`	Binary Web stream, Node Readable, or async iterable of Uint8Array.
`Source.fromResponse(response, options?)`	Existing fetch Response.
`Source.fromText(text, options?)`	UTF-8 text; defaults to `document.txt`.
`Source.fromFileId(id, options?)`	Existing upload ID. Original bytes cannot be downloaded.
`Source.fromArtifact(metadata, { client, result }?)`	Existing artifact. Bind its client for byte reads; include a receipt to select its other variants.

Factories accept filename, contentType, maxBytes, and upload lifetime options. Use lifetime: "persistent" for reusable templates. Options on an existing file ID do not change the server-side file’s lifetime or name. The filename determines input format. URL/Response sources infer it from Content-Disposition or the URL path; supply one for opaque URLs or unnamed Blobs. Source URLs use their own credentials, never your Revise key. Redirects are disabled. Enforce your own network access policy when accepting URLs from users.

Read output

bytes({ signal, maxBytes }) returns an independent Uint8Array.
blob(options) returns an immutable Blob.
stream(options) returns a fresh Web stream after buffering and verification.
save(path, options) writes to an explicit local path; Node only.

Source reads verify artifact length and SHA-256. The default read limit is 64 MiB; set maxBytes for larger encrypted output. Upload resolution always caps at 18 MiB. These limits bound file size, not total process memory. Successful reads are cached snapshots. For retryable stream input, provide a factory that opens a new stream after a failure. A failed one-shot stream or Response cannot restart; concurrent readers can share that failure. See error recovery before resubmitting work after a timeout.

Configuration and deadlines

import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({
  apiKey: process.env.REVISE_API_KEY!,
  baseUrl: "https://revise.io/api", // omit /v1
  timeoutMs: 1_000_000,
  pollIntervalMs: 1_000,
  maxRetries: 2,
  maxRetryDelayMs: 60_000,
});

These values are the defaults. timeoutMs applies to workflows and waits, not individual REST calls; supply { signal } to bound an individual call. edit/convert timeouts cover source resolution through polling. Read the returned Source with its own signal to bound the later download. Aborting locally does not cancel the server job. High-level options use outputEncryption, responseOptions (edit only), trackedChanges (edit only), inference, limits, metadata, and retention. REST-shaped methods use wire names such as output_encryption. onProgress is synchronous and exposes recovery keys and known IDs at workflow transitions; use low-level calls when you must await durable storage between steps.

REST methods

The client returns server JSON without renaming fields. Each endpoint page includes an example.

Resource	Methods
`files`	`upload`, `get`, `delete`
`prompts`	`create`, `get`, `list`, `cancel`, `resume`, `deleteContent`, `wait`, `run`
`conversions`	`create`, `get`, `list`, `cancel`, `deleteContent`, `wait`, `run`
`artifacts`	`get`, `content`, `download`
`account`	`get`, `ledger`, `topup`
`models`	`list`
`usage`	`get`
`webhooks`	`create`, `list`, `delete`, `deliveries`, `retry`

create returns immediately after submission. wait(idOrReceipt) returns any non-running receipt, including paused or failed work. run(body) requires success and throws ReviseJobError otherwise. Use prompts.run for text-only, read, or comment requests. Every endpoint accepts { signal, idempotencyKey } as its final options argument. Creation methods generate a key when omitted; supply a stable key to recover across restarts. Lists preserve next_cursor; pass it with the same filters for the next page. Query dates are RFC3339 strings, metadata filters are objects, and group_by is a comma-separated string. artifacts.download(idOrMetadata, options) fetches and verifies bytes. artifacts.content(id) returns a raw Response that your code must consume and verify. promptFile(file, body) and convertFile(file, body) provide eager upload/job/download workflows when you want the receipt and all output bytes together; their deadlines include downloads. The package exports PromptRequest, Prompt, ConversionRequest, Conversion, Artifact, UploadedFile, options/error types, and OpenAPI-generated components/paths. getResponseMetadata(result) exposes HTTP headers, status, Location, and replay information for original JSON results. Source receipt/metadata getters return defensive copies, so response metadata is not attached to those copies. See errors and retries for error classes, retry defaults, and recovery after an ambiguous submission.

Getting started

Guides

REST reference

Edit and convert

Create a Source

Read output

Configuration and deadlines

REST methods

​Edit and convert

​Create a Source

​Read output

​Configuration and deadlines

​REST methods

Edit and convert

Create a Source

Read output

Configuration and deadlines

REST methods