Prompts and document edits

POST /v1/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 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, then submit its ID:

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}. 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:

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

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.

Getting started

Guides

REST reference

Inputs and outputs

Edit a document

Review without editing

Continue or branch

​Inputs and outputs

​Edit a document

​Review without editing

​Continue or branch

Inputs and outputs

Edit a document

Review without editing

Continue or branch