> ## 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.

# Prompts and document edits

> Read, review, and edit documents, with clean and tracked DOCX output.

[`POST /v1/prompt`](/developer/docs/developer/docs/revise-api/reference/create-prompt) requires a nonempty `prompt`. Use it without a target for text requests, or supply one document with the access your workflow needs.

| `document_access` | Behavior |
| - | - |
| `read` (default) | Read the document and return an assistant response. |
| `comment` | Read and add review comments without editing the document text. |
| `edit` | Edit and comment; automatically export document artifacts. |

For read or comment requests, set `export_document: true` if you also need an exported document. Comment/edit access and export require a target; to draft a new document, upload a starting file first.

## Inputs and outputs

Prompt targets support **DOCX, UTF-8 Markdown, HTML, and plain text**, including `.markdown` and `.htm` aliases. Uploading other formats does not make them readable by a prompt: [convert](/developer/docs/developer/docs/revise-api/conversions) PDF, images, RTF, or ODT to DOCX first.

Supply `inputs: [{"role":"target","file_id":"file_…"}]`, or use an eligible `artifact_id`. Exactly one target is supported. Remote URLs and additional reference files are not REST inputs; the TypeScript `Source.fromUrl` helper downloads and uploads on your application's behalf.

Document exports always contain two DOCX artifacts:

* `clean`: pending revisions accepted.
* `tracked_changes`: revisions kept, for review in Word or another compatible editor.

Select by `variant`, not array order. Convert the chosen artifact separately if you need PDF, Markdown, HTML, or text. Tracked output can include revisions already present in the input; clean output accepts those pending revisions too.

## Edit a document

First [upload the file](/developer/docs/developer/docs/revise-api/files), then submit its 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. Preserve the remaining wording.",
    "document_access":"edit",
    "inputs":[{"role":"target","file_id":"file_REPLACE_ME"}]
  }'
```

Poll [`GET /v1/prompt/{id}`](/developer/docs/developer/docs/revise-api/reference/get-prompt). A `succeeded` job can be partial. Inspect `incomplete`, `stop_reason`, and the assistant's `message.content` before treating the instruction as complete. `stop_reason` identifies `spending_limit` or `time_limit` when applicable.

The same edit in 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.fromPath("contract.docx"),
  "Change the payment term to 30 days. Preserve the remaining wording.",
  { idempotencyKey: "contract-42" },
);
console.log(edited.result);
await edited.save("contract-clean.docx");
await edited.variant("tracked_changes").save("contract-review.docx");
```

## Review without editing

```ts theme={null}
import { ReviseClient } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const review = await revise.prompts.run({
  prompt: "Flag ambiguous payment terms and explain each concern in a comment.",
  document_access: "comment",
  export_document: true,
  inputs: [{ role: "target", file_id: "file_REPLACE_ME" }],
}, { idempotencyKey: "contract-42-review" });

console.log(review.message?.content);
for (const comment of review.comments ?? []) {
  console.log(comment.id, comment.parentId, comment.bodyMd);
}
```

`comments` is a flat list of native comment records; replies identify their parent with `parentId`. `changes` lists pending tracked changes, including IDs, kinds, affected `blockIds`, and available inserted/deleted text. These native objects use camelCase fields. The DOCX carries document anchors and review markup.

To reduce JSON response size, set `response_options.include_comments` or `include_changes` to `false`. This omits those fields from receipts without removing comments or revisions from the document. Omitted options inherit from a predecessor or reused artifact; otherwise both default to `true`.

## Continue or branch

| Input | Use it when |
| - | - |
| `previous_prompt_id` | Continuing the latest successful request in the same conversation, with its working document and available conversation context. |
| `inputs[].artifact_id` | Starting a new conversation from a selected document variant, without the earlier chat history. |
| `inputs[].file_id` | Starting from an uploaded original or reusable template. |

A continuation must use the current successful conversation head, with no other request active. A stale or busy predecessor returns `409 stale_or_busy_conversation`; `error.details.current_head_prompt_id` identifies the current head. Do not combine `previous_prompt_id` with `inputs`. Access still defaults to `read`, so repeat `document_access: "edit"` for further edits.

Inspect `continuation` to see whether reasoning state was reused, reset, or compacted. Provider/model choices inherit from the predecessor when omitted; explicitly changing them can affect continuity.

Only artifacts with `input_eligible: true` can be reused directly. Request content must still be retained. Encrypted output disables both continuation and direct artifact reuse; see [output encryption](/developer/docs/developer/docs/revise-api/encryption).


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