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

# Prompts and document edits

> Read, comment on, and edit documents with an asynchronous prompt.

[`POST /v1/prompt`](/revise-api/reference/create-prompt) requires only `prompt`. Without a document target, use it for text requests. With a target, select the access the request needs.

| `document_access` | Behavior                                                   |
| ----------------- | ---------------------------------------------------------- |
| `read`            | Read the document without editing it; this is the default. |
| `comment`         | Review the document and add comments.                      |
| `edit`            | Edit the document and produce document output.             |

For a read or comment request that needs an exported document, set `export_document: true`.

## Edit an uploaded document

First [upload your file](/revise-api/files) and use its returned ID:

```bash theme={null}
curl --fail-with-body 'https://revise.io/api/v1/prompt' \
  -H "Authorization: Bearer $REVISE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: contract-42-edit' \
  -d '{
    "prompt":"Change the payment term to 30 days.",
    "document_access":"edit",
    "inputs":[{"role":"target","file_id":"file_REPLACE_ME"}]
  }'
```

Poll [`GET /v1/prompt/{id}`](/revise-api/reference/get-prompt). The receipt includes status, message, changes, comments, artifacts, usage, and errors. Select an artifact by its `variant`, such as `clean` or `tracked_changes`, rather than assuming array order.

A successful prompt can still report `incomplete` or a `stop_reason`. Inspect those fields when your workflow requires the entire instruction to be completed.

## Continue work

An input is one target with exactly one `file_id` or eligible `artifact_id`. The current API supports one target, not a list of reference documents. An artifact with `input_eligible: true` can be used directly by another unencrypted prompt. `previous_prompt_id` supports eligible continuation; do not combine it with a new target.

Encrypted artifacts cannot be reused directly. A new request with output encryption also cannot use `artifact_id` or `previous_prompt_id`, even if its input is plaintext. Download the plaintext and upload it as a new file first. See [encryption](/revise-api/encryption).

## TypeScript

```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.fromUrl("https://example.com/contract.docx"),
  "Change the payment term to 30 days.",
  { idempotencyKey: "contract-42" },
);
const clean = await edited.bytes();
const tracked = await edited.variant("tracked_changes").bytes();
```

For direct REST-shaped requests, use `revise.prompts.create(body)` to return immediately or `revise.prompts.run(body)` to wait for success. For example, a review uses `document_access: "comment"` and `export_document: true`; the high-level `edit` helper always requests edit access.