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

# Create a prompt

This call returns an admission receipt. Poll the get endpoint until work stops, then download the artifacts. See [job lifecycle](/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 openapi/revise-api.json POST /v1/prompt
openapi: 3.1.0
info:
  title: Revise API
  version: 0.1.0
  description: >-
    Queued document prompting and file conversion. Conversion supports the same
    formats as revise.io/converter, including semantic PDF/image scanning. USD
    responses are exact decimal strings. Same-origin downloads require Bearer
    auth. Account provider keys (BYOK) are pinned at admission. Request content
    expires 24 hours after terminal completion; encrypted artifacts use compact
    JWE RSA-OAEP-256/A256GCM.
servers:
  - url: https://revise.io/api
security:
  - apiKey: []
paths:
  /v1/prompt:
    post:
      summary: Queue a prompt with its maximum authorized cost
      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: >-
            Queued. The request is admitted while the account balance is
            positive; its spending thresholds stop new model calls based on
            observed costs; the final charge can exceed them.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Prompt'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PromptRequest:
      type: object
      properties:
        prompt:
          type: string
          minLength: 1
          maxLength: 1048576
        document_access:
          enum:
            - read
            - comment
            - edit
          default: read
        previous_prompt_id:
          type: string
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/Target'
          maxItems: 1
        export_document:
          type: boolean
        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: >-
        Prompt the shared Revise agent. Native web search is enabled by default.
        Provider-reported token usage and search fees are included in inference
        charges, with the configured premium and soft customer spending
        thresholds. When the account holds a provider key for the resolved
        provider the request runs on that key: the key is pinned at admission,
        deleting or replacing it fails the request at its next model call with
        credential_unavailable (no managed fallback), and provider error text is
        withheld from results.
      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/NativeCommentThread'
          description: >-
            Omitted when disabled by the stored response_options. Otherwise
            returns the existing native schema.
        changes:
          type: array
          items:
            $ref: '#/components/schemas/NativeTrackedChange'
          description: >-
            Omitted when disabled by the stored response_options. Otherwise
            returns the existing native schema.
        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_platform_cost_usd
            - max_inference_cost_usd
            - 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
      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: >-
        The base fee is graduated per API account each UTC calendar month:
        requests 1-1000 $0.05, 1001-5000 $0.035, 5001-10000 $0.02, then $0.01.
        Each newly accepted request counts once across all keys, including later
        failures/cancellations. Retries with the same idempotency key do not
        count again. The rate is pinned on admission; CPU and inference rates do
        not change with volume.
      type: object
      properties:
        max_platform_cost_usd:
          description: >-
            Soft spending threshold. New model calls stop when observed platform
            cost reaches this amount; active responses and tools finish and are
            billed in full.
          oneOf:
            - type: string
              pattern: ^[0-9]+(\.[0-9]{1,9})?$
            - type: number
              minimum: 0
              maximum: 1000000
        max_inference_cost_usd:
          description: >-
            Soft spending threshold checked against reported inference cost,
            including premium and search. No predicted cost is reserved; the
            last response may exceed this amount and is billed in full. On a
            request billed by the account's own provider key the threshold
            meters the provider's list-price spend instead; Revise still charges
            nothing for that inference.
          oneOf:
            - type: string
              pattern: ^[0-9]+(\.[0-9]{1,9})?$
            - type: number
              minimum: 0
              maximum: 1000000
        max_seconds:
          type: integer
          minimum: 120
          maximum: 3600
          description: >-
            Soft work budget in seconds (minimum 120). Active model responses
            finish normally; no new turn starts after the deadline, and exports
            may finish later.
      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
        model:
          type: string
        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
    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
    NativeCommentThread:
      type: object
      description: >-
        Unmodified native ReviseCommentThread projection; camelCase fields and
        many-to-one suggestion links are retained.
      required:
        - root
        - replies
      properties:
        root:
          type: object
          additionalProperties: true
        replies:
          type: array
          items:
            type: object
            additionalProperties: true
        anchor:
          anyOf:
            - type: object
              additionalProperties: true
            - type: 'null'
        relatedSuggestionIds:
          type: array
          items:
            type: string
      additionalProperties: true
    NativeTrackedChange:
      type: object
      description: Unmodified native ReviseTrackedChange projection.
      required:
        - id
        - kind
      properties:
        id:
          type: string
        kind:
          type: string
        blockIds:
          type: array
          items:
            type: string
        commentThreadId:
          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
        content_type:
          type: string
        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: >-
            Same-origin path. Requires the same Bearer API key; never a public
            signed link in this local build.
        input_eligible:
          type: boolean
          description: >-
            False for encrypted artifacts; they must be decrypted locally and
            re-uploaded.
        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
      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 output-word 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:
            output_words:
              type: integer
              minimum: 0
            rate_usd_per_1000_words:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.020000000'
            minimum_fee_usd:
              type: string
              pattern: ^-?[0-9]+\.[0-9]{9}$
              example: '0.100000000'
          required:
            - output_words
            - rate_usd_per_1000_words
            - minimum_fee_usd
          additionalProperties: false
          description: >-
            Present on settled conversion receipts. The base_fee_usd cost item
            is max(minimum_fee_usd, output_words multiplied by the per-word
            rate).
        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-v5-monthly-fees
        platform:
          tool_cpu_seconds: '1.000000'
          tool_cpu_rate_usd_per_second: '0.001000000'
        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.061000000'
          itemized:
            base_fee_usd: '0.050000000'
            cpu_fee_usd: '0.001000000'
            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>.

````