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

# Create a prompt

> Submit a text request or read, comment on, or edit one document. Prompt targets support DOCX, Markdown, HTML, and plain text. Convert other upload formats first. Edit access exports clean and tracked-changes DOCX artifacts; read/comment access requires export_document=true to export. A 202 response confirms admission; poll the receipt for completion and inspect incomplete and stop_reason even on success. Use /v1/models for supported providers and models.

See [prompt workflows](/developer/docs/developer/docs/revise-api/prompts) for integration guidance.

This call returns an admission receipt. Poll the get endpoint until work stops, then inspect the result and download its artifacts. See [job lifecycle](/developer/docs/developer/docs/revise-api/jobs).

## TypeScript

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

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.prompts.create(
  { prompt: "Write a short welcome message." },
  { idempotencyKey: "welcome-42" },
);
```


## OpenAPI

````yaml developer/docs/openapi/revise-api.json POST /v1/prompt
openapi: 3.1.0
info:
  title: Revise API
  version: 0.1.0
  description: >-
    Asynchronous document prompts and format conversions. Submit a job, poll its
    receipt or receive a webhook, then download its artifacts. USD amounts are
    exact decimal strings. Job content expires 24 hours after terminal
    completion. All account endpoints require a bearer API key.
servers:
  - url: https://revise.io/api
security:
  - apiKey: []
paths:
  /v1/prompt:
    post:
      summary: Create a prompt
      description: >-
        Submit a text request or read, comment on, or edit one document. Prompt
        targets support DOCX, Markdown, HTML, and plain text. Convert other
        upload formats first. Edit access exports clean and tracked-changes DOCX
        artifacts; read/comment access requires export_document=true to export.
        A 202 response confirms admission; poll the receipt for completion and
        inspect incomplete and stop_reason even on success. Use /v1/models for
        supported providers and models.
      operationId: createPrompt
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 200
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptRequest'
      responses:
        '202':
          description: >-
            Admission receipt, including on idempotent replay. May already be
            running or terminal. Save the ID and poll for the result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
          headers:
            Location:
              description: Account-authenticated path to retrieve this resource.
              schema:
                type: string
            Idempotent-Replayed:
              description: Present with value true on an idempotent replay.
              schema:
                type: string
                enum:
                  - 'true'
            Retry-After:
              description: Suggested delay before polling, in seconds.
              schema:
                type: string
                example: '1'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PromptRequest:
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 1048576
          description: >-
            Nonempty instruction, at most 1 MiB of UTF-8 bytes. The entire JSON
            body is limited to 2 MiB.
        document_access:
          enum:
            - read
            - comment
            - edit
          default: read
        previous_prompt_id:
          type: string
          description: >-
            Latest successful head of the same conversation, with retained
            content and no active successor. Cannot be combined with inputs.
            Inherits provider/model and omitted response options;
            document_access still defaults to read. Encrypted-output requests
            cannot be continued.
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/Target'
          maxItems: 1
          description: >-
            At most one target, with exactly one file_id or artifact_id.
            Uploaded targets support DOCX, Markdown, HTML, and text. Direct
            artifact inputs require input_eligible=true and an unencrypted new
            request.
        export_document:
          type: boolean
          default: false
          description: >-
            Export clean and tracked-changes DOCX artifacts for read/comment
            requests. edit always exports. Requires a target.
        limits:
          $ref: '#/components/schemas/Limits'
        inference:
          $ref: '#/components/schemas/InferenceRequest'
        metadata:
          $ref: '#/components/schemas/Metadata'
        output_encryption:
          $ref: '#/components/schemas/OutputEncryption'
        response_options:
          $ref: '#/components/schemas/ResponseOptions'
        retention:
          $ref: '#/components/schemas/RetentionOptions'
      required:
        - prompt
      additionalProperties: false
      description: >-
        Submit text-only work or one document target. comment/edit access and
        export require a document. Native web search is enabled. The resolved
        provider credential is pinned at submission; replacing or deleting it
        can fail the next model call without managed fallback. See the guides
        for pricing, continuation, and retention.
      example:
        prompt: >-
          Rewrite this paragraph in a clear, professional tone: We got your
          request and will get back to you soon.
        document_access: read
        metadata:
          customer: acme
          environment: development
    Prompt:
      type: object
      properties:
        id:
          type: string
        conversation_id:
          type: string
        previous_prompt_id:
          anyOf:
            - type: string
            - type: 'null'
        status:
          enum:
            - queued
            - running
            - paused
            - succeeded
            - failed
            - cancelled
        created_at:
          type: string
          format: date-time
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        conversation_expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
        message:
          anyOf:
            - $ref: '#/components/schemas/Message'
            - type: 'null'
        continuation:
          $ref: '#/components/schemas/Continuation'
        comments:
          type: array
          items:
            $ref: '#/components/schemas/NativeComment'
          description: >-
            Flat native comment records; replies use parentId. Omitted when
            disabled by response_options or when content is unavailable.
        changes:
          type: array
          items:
            $ref: '#/components/schemas/NativeTrackedChange'
          description: >-
            Pending native tracked changes. Replacements can appear as linked
            insertion/deletion entries. Omitted when disabled by
            response_options or when content is unavailable.
        artifacts:
          type: array
          items:
            $ref: '#/components/schemas/Artifact'
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        metadata:
          $ref: '#/components/schemas/Metadata'
        inference:
          type: object
          properties:
            provider:
              enum:
                - openai
                - anthropic
                - xai
                - gemini
            model:
              type: string
            billing:
              enum:
                - revise
                - provider
              description: >-
                The billing that applied at admission; fixed for the life of the
                request even if account keys change later.
          required:
            - provider
            - model
            - billing
          additionalProperties: false
        limits:
          type: object
          properties:
            max_platform_cost_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.050000000'
            max_inference_cost_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.050000000'
            max_seconds:
              type: integer
          required:
            - max_seconds
          additionalProperties: false
        error:
          anyOf:
            - type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                details:
                  type: object
                  additionalProperties: true
              required:
                - code
                - message
              additionalProperties: false
            - type: 'null'
        api_key_id:
          type:
            - string
            - 'null'
          description: >-
            Non-secret ID of the key that originally submitted this prompt; null
            when not recorded. Idempotent retries preserve the original key.
        output_encrypted:
          type: boolean
          description: >-
            True disables continuation and reuse. Artifacts are encrypted for
            the supplied public key.
        content_expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            24 hours after terminal completion. Result content and new
            continuation become unavailable at this deadline.
        content_deleted_at:
          type:
            - string
            - 'null'
          format: date-time
        retention:
          $ref: '#/components/schemas/RetentionOptions'
        incomplete:
          type: boolean
          description: True when the request returned a partial result.
        stop_reason:
          type: string
          enum:
            - spending_limit
            - time_limit
          description: >-
            Limit that ended further agent work. The current result is returned;
            successful partial results incur the base fee even without
            inference, plus actual billable usage.
      required:
        - id
        - conversation_id
        - previous_prompt_id
        - status
        - created_at
        - completed_at
        - conversation_expires_at
        - message
        - continuation
        - artifacts
        - usage
        - metadata
        - inference
        - limits
        - error
        - api_key_id
        - output_encrypted
        - incomplete
        - content_expires_at
        - content_deleted_at
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            details:
              type: object
              additionalProperties: true
          required:
            - code
            - message
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    Target:
      type: object
      properties:
        role:
          const: target
        file_id:
          type: string
        artifact_id:
          type: string
      required:
        - role
      additionalProperties: false
      oneOf:
        - required:
            - file_id
          not:
            required:
              - artifact_id
        - required:
            - artifact_id
          not:
            required:
              - file_id
    Limits:
      description: >-
        Optional execution and spending thresholds. Spending limits are opt-in:
        omitted cost limits are unlimited. The time limit defaults to 900
        seconds. Prompt platform cost is base fee plus tool CPU; conversion
        platform cost is its flat/page fee. Prompt cost limits may each be at
        most $500,000; conversion cost limits may each be at most $1,000,000.
        These thresholds do not reserve account credit.
      type: object
      properties:
        max_platform_cost_usd:
          description: >-
            Platform spending threshold. Must cover the applicable
            base/conversion fee, or one scan page. A scan checks its full page
            fee before inference. For prompts, no new model call starts once
            observed platform spend reaches this threshold; active work may
            exceed it. Omit for no per-request spending limit. Must be greater
            than zero when supplied.
          oneOf:
            - type: string
              pattern: ^(?=[0-9.]*[1-9])[0-9]+(\.[0-9]{1,9})?$
            - type: number
              maximum: 1000000
              exclusiveMinimum: 0
        max_inference_cost_usd:
          description: >-
            Soft inference threshold, including managed prompt premium and
            search. Active responses can exceed it. With your own provider key
            it meters provider list-price spend, while Revise charges no
            inference fee. For managed scans, scan inference is included in the
            page fee but remains subject to this threshold. Omit for no
            per-request spending limit. Must be greater than zero when supplied.
          oneOf:
            - type: string
              pattern: ^(?=[0-9.]*[1-9])[0-9]+(\.[0-9]{1,9})?$
            - type: number
              maximum: 1000000
              exclusiveMinimum: 0
        max_seconds:
          type: integer
          minimum: 120
          maximum: 3600
          description: >-
            Work budget in seconds, starting when a worker begins, excluding
            queue time. Prompts stop new turns at the deadline; active responses
            and exports can finish later.
          default: 900
      required: []
      additionalProperties: false
      example:
        max_platform_cost_usd: '2.000000000'
        max_inference_cost_usd: '3.000000000'
        max_seconds: 900
    InferenceRequest:
      type: object
      properties:
        provider:
          enum:
            - openai
            - anthropic
            - xai
            - gemini
          description: >-
            Public provider ID. Omit for the API default on a new conversation,
            or inherit from previous_prompt_id.
        model:
          type: string
          description: >-
            Exact model ID from /v1/models, or default. Omitting it selects the
            provider default, except when inherited from a predecessor.
        billing:
          enum:
            - revise
            - provider
          description: >-
            Which party pays for inference. Omitted or "revise" is automatic:
            the account's stored key for the resolved provider is used when
            present (billed by the provider, no Revise inference charge),
            otherwise managed inference applies. "provider" requires a stored
            key for the resolved provider and fails admission with
            provider_key_required instead of falling back. Provider resolution
            includes defaults and predecessor inheritance, so an omitted
            provider still uses the account key.
      required: []
      additionalProperties: false
    Metadata:
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 512
      propertyNames:
        minLength: 1
        maxLength: 64
      example:
        customer: acme
        environment: production
      description: >-
        Up to 16 string values for application attribution. Keys are 1–64 UTF-8
        bytes; values at most 512 UTF-8 bytes. Metadata is deleted with request
        content; persist your own job mapping for long-term attribution.
    OutputEncryption:
      type: object
      additionalProperties: false
      required:
        - format
        - public_key_pem
      properties:
        format:
          type: string
          enum:
            - jwe
        public_key_pem:
          type: string
          maxLength: 16384
          description: >-
            RSA SubjectPublicKeyInfo PEM (BEGIN PUBLIC KEY), 2048–8192 bits.
            Private keys, certificates and key URLs are rejected.
      description: >-
        Encrypt exported artifact bytes using compact JWE, RSA-OAEP-256 and
        A256GCM. Only encrypted files are downloadable. Disables prompt
        continuation and artifact reuse; cannot be combined with
        previous_prompt_id or artifact_id input. Prompts require editing or
        export_document=true.
    ResponseOptions:
      type: object
      additionalProperties: false
      properties:
        include_comments:
          type: boolean
          default: true
        include_changes:
          type: boolean
          default: true
      description: >-
        Persisted response policy. False omits the corresponding top-level JSON
        field from submission, polling, history and replay responses; it does
        not change the document or native state. Omitted options inherit from an
        unencrypted predecessor or reused artifact, otherwise default to true.
    RetentionOptions:
      type: object
      additionalProperties: false
      properties:
        delete_after_webhook_id:
          type: string
          pattern: ^wh_[0-9a-f-]{36}$
          description: >-
            Account-owned endpoint subscribed to prompt.completed or
            conversion.completed, matching the request kind. Its successful
            acknowledgement deletes request content and ephemeral source.
            Download everything before returning 2xx.
      required:
        - delete_after_webhook_id
    Message:
      type: object
      properties:
        role:
          const: assistant
        content:
          type: string
        incomplete:
          type: boolean
        citations:
          type: array
          items:
            $ref: '#/components/schemas/Citation'
      required:
        - role
        - content
        - incomplete
      additionalProperties: false
    Continuation:
      type: object
      properties:
        reasoning_state:
          enum:
            - new
            - reused
            - reset
            - compacted
            - unavailable
        history_compacted:
          anyOf:
            - type: boolean
            - type: 'null'
        reason:
          type: string
      required:
        - reasoning_state
        - history_compacted
      additionalProperties: false
    NativeComment:
      type: object
      description: >-
        Flat native comment record. Replies use parentId. Anchors are carried in
        the document, with anchorBlockId available for structural anchors.
        Native fields retain camelCase.
      required:
        - id
        - author
        - createdAt
        - bodyMd
      additionalProperties: true
      properties:
        id:
          type: string
        author:
          type: string
        initials:
          type: string
        authorId:
          type: string
        authorImageUrl:
          type: string
        createdAt:
          type: string
          format: date-time
        bodyMd:
          type: string
          description: Comment text in Markdown.
        parentId:
          type: string
          description: Parent comment ID for a reply; absent for a root comment.
        agentRequestId:
          type: string
        agentConversationId:
          type: string
        agentName:
          type: string
        agentModel:
          type: string
        suggestionId:
          type: string
        anchorBlockId:
          type: string
        agentTriggerIds:
          type: array
          items:
            type: string
        relatedSuggestionIds:
          type: array
          items:
            type: string
        resolved:
          type: boolean
        authorType:
          enum:
            - human
            - ai
        importedId:
          type: integer
        citations:
          type: array
          items:
            $ref: '#/components/schemas/Citation'
        mentions:
          type: array
          items:
            type: object
            required:
              - id
              - type
              - label
              - start
              - end
            properties:
              id:
                type: string
              type:
                enum:
                  - user
                  - agent
              label:
                type: string
              start:
                type: integer
              end:
                type: integer
              email:
                type: string
            additionalProperties: true
    NativeTrackedChange:
      type: object
      description: >-
        Pending tracked change with native camelCase fields. May include
        revisions already present in the input.
      required:
        - id
        - kind
        - author
        - authorType
        - blockIds
      properties:
        id:
          type: string
        kind:
          enum:
            - insert
            - delete
            - format
            - move
        blockIds:
          type: array
          items:
            type: string
        commentThreadId:
          type: string
        author:
          type: string
        agentModel:
          type: string
        description:
          type: string
        insertedText:
          type: string
        deletedText:
          type: string
        authorType:
          enum:
            - human
            - ai
        createdAt:
          type: number
          description: Unix time in milliseconds, when recorded.
        moveSourceBlockIds:
          type: array
          items:
            type: string
        moveDestinationBlockIds:
          type: array
          items:
            type: string
      additionalProperties: true
    Artifact:
      type: object
      properties:
        id:
          type: string
        prompt_id:
          type: string
        conversion_id:
          type: string
        format:
          enum:
            - docx
            - pdf
            - md
            - html
            - txt
        filename:
          type: string
          description: >-
            Original plaintext filename, even when encrypted. Encrypted
            downloads append .jwe.
        content_type:
          type: string
          description: >-
            Original plaintext MIME type. Encrypted downloads use
            application/jose.
        variant:
          enum:
            - tracked_changes
            - clean
            - converted
        sha256:
          type: string
          description: >-
            SHA-256 of the exact downloadable bytes (ciphertext for encrypted
            artifacts).
        bytes:
          type: integer
          description: >-
            Size of the downloadable bytes, including JWE encoding overhead when
            encrypted.
        download_url:
          type: string
          description: >-
            Account-authenticated API path. The endpoint may redirect to signed
            storage; never forward bearer credentials to storage.
        input_eligible:
          type: boolean
          description: >-
            True only for an unexpired, undeleted, unencrypted prompt artifact.
            Conversion artifacts are not directly reusable; download and upload
            them first.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        encryption:
          $ref: '#/components/schemas/ArtifactEncryption'
        deleted_at:
          type:
            - string
            - 'null'
          format: date-time
      required:
        - id
        - format
        - filename
        - content_type
        - variant
        - sha256
        - bytes
        - download_url
        - input_eligible
        - expires_at
        - deleted_at
      additionalProperties: false
    Usage:
      type: object
      properties:
        pricing_version:
          type: string
        platform:
          type: object
          properties:
            tool_cpu_seconds:
              type: string
              pattern: ^[0-9]+\.[0-9]{6}$
              example: '1.250000'
            tool_cpu_rate_usd_per_second:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.050000000'
          required:
            - tool_cpu_seconds
            - tool_cpu_rate_usd_per_second
          additionalProperties: false
        inference:
          type: object
          properties:
            billed_by:
              enum:
                - revise
                - provider
              description: >-
                "provider" when the account's own key paid the supplier:
                inference_fee_usd is then zero, token counts are still reported,
                and no supplier amount is exposed.
            input_tokens:
              type: integer
              minimum: 0
            cached_input_tokens:
              type: integer
              minimum: 0
            cache_creation_input_tokens:
              type: integer
              minimum: 0
            output_tokens:
              type: integer
              minimum: 0
            web_search_requests:
              type: integer
              minimum: 0
            web_search_unit:
              type: string
              enum:
                - calls
                - queries
                - grounded_prompts
          required:
            - billed_by
          additionalProperties: false
          description: >-
            Includes model input, cache reads/writes, output and reasoning,
            compaction, and native web/X search or Google grounding. Search
            units depend on provider. Provider-reported usage counts are omitted
            on older receipts. For conversions, managed scan inference is
            included in the per-page conversion fee, so inference_fee_usd is
            zero. Aggregate token counts do not imply a single inference rate;
            historical per-category rates are not available in this receipt.
        conversion:
          type: object
          properties:
            unit:
              enum:
                - conversion
                - page
                - word
              description: >-
                conversion: flat fee for a non-scanned input. page: PDF/image
                pages actually scanned. word: only on conversions admitted under
                the superseded local-v7-conversion-words pricing.
            quantity:
              type: integer
              minimum: 0
              description: >-
                Units billed: 1 (or 0 if unbilled) for conversion, scanned pages
                for page, output words for word.
            unit_price_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.020000000'
            minimum_fee_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              description: Only present for unit word.
          required:
            - unit
            - quantity
            - unit_price_usd
          additionalProperties: false
          description: >-
            Conversion billing details retained after content deletion. For
            billed work, base_fee_usd is quantity × unit_price_usd (historical
            word pricing applies a minimum). Read settled cost for the actual
            charge.
        cost:
          $ref: '#/components/schemas/Cost'
      required:
        - pricing_version
        - platform
        - inference
        - cost
      additionalProperties: false
      description: >-
        Customer-facing settled charges and usage. Supplier costs, margins and
        internal reconciliation diagnostics are not exposed. Historical charges
        are never recalculated using current prices.
      example:
        pricing_version: local-v8-conversion-pages
        platform:
          tool_cpu_seconds: '1.000000'
          tool_cpu_rate_usd_per_second: '0.050000000'
        inference:
          billed_by: revise
          input_tokens: 1200
          cached_input_tokens: 400
          cache_creation_input_tokens: 0
          output_tokens: 200
          web_search_requests: 1
          web_search_unit: calls
        cost:
          total_usd: '0.110000000'
          itemized:
            base_fee_usd: '0.050000000'
            cpu_fee_usd: '0.050000000'
            inference_fee_usd: '0.010000000'
    Citation:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        title:
          type: string
        startIndex:
          type: integer
        endIndex:
          type: integer
      required:
        - id
        - url
        - title
      additionalProperties: false
    ArtifactEncryption:
      type: object
      additionalProperties: false
      required:
        - format
        - alg
        - enc
        - key_id
      properties:
        format:
          type: string
          enum:
            - jwe
        alg:
          type: string
          enum:
            - RSA-OAEP-256
        enc:
          type: string
          enum:
            - A256GCM
        key_id:
          type: string
          description: >-
            Base64url SHA-256 JWK thumbprint of the recipient public key
            (RFC7638).
    Cost:
      type: object
      additionalProperties: false
      required:
        - total_usd
        - itemized
      properties:
        total_usd:
          type: string
          pattern: ^[0-9]+\.[0-9]{9}$
          example: '0.305000000'
        itemized:
          type: object
          additionalProperties: false
          required:
            - base_fee_usd
            - cpu_fee_usd
            - inference_fee_usd
          properties:
            base_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.250000000'
            cpu_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.005000000'
            inference_fee_usd:
              type: string
              pattern: ^[0-9]+\.[0-9]{9}$
              example: '0.050000000'
      example:
        total_usd: '0.305000000'
        itemized:
          base_fee_usd: '0.250000000'
          cpu_fee_usd: '0.005000000'
          inference_fee_usd: '0.050000000'
      description: >-
        Settled customer charges. Itemized base, CPU and inference fees are
        disjoint and sum exactly to total_usd. Inference includes model
        processing and web search. No overlapping platform subtotal. Balances
        and limits are separate from cost.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Revise API key from https://revise.io/console/api-keys. Send
        Authorization: Bearer <key>.

````

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