> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript client

> Use @reviseio/api for typed REST calls and document workflows.

`@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.

```bash theme={null}
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.

```ts theme={null}
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](/developer/docs/developer/docs/revise-api/errors) before resubmitting work after a timeout.

## Configuration and deadlines

```ts theme={null}
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](/developer/docs/developer/docs/revise-api/errors) for error classes, retry defaults, and recovery after an ambiguous submission.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.