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

# List prompts

> Returns the same Prompt objects as GET /v1/prompt/{id}. Pass next_cursor as cursor for the next page; null means the end. Ordering is created_at descending, then ID descending. Cursors belong to the authenticated account. Newly submitted requests do not shift subsequent pages. Invalid limits or cursors return 400. Filters combine with AND. Repeat the same filters on each page. Status reflects current state, so this is not a frozen snapshot of mutable fields. Unknown and duplicate parameters return 400.

## TypeScript

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

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
const result = await revise.prompts.list({ limit: 20, metadata: { customer: "acme" } });
```


## OpenAPI

````yaml openapi/revise-api.json GET /v1/prompts
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/prompts:
    get:
      summary: List account prompts, newest first
      description: >-
        Returns the same Prompt objects as GET /v1/prompt/{id}. Pass next_cursor
        as cursor for the next page; null means the end. Ordering is created_at
        descending, then ID descending. Cursors belong to the authenticated
        account. Newly submitted requests do not shift subsequent pages. Invalid
        limits or cursors return 400. Filters combine with AND. Repeat the same
        filters on each page. Status reflects current state, so this is not a
        frozen snapshot of mutable fields. Unknown and duplicate parameters
        return 400.
      operationId: listPrompts
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          schema:
            type: string
          description: The next_cursor returned by the previous page.
        - name: status
          in: query
          schema:
            type: string
            enum:
              - queued
              - running
              - paused
              - succeeded
              - failed
              - cancelled
        - name: conversation_id
          in: query
          schema:
            type: string
          description: Exact conv_ ID.
        - name: api_key_id
          in: query
          schema:
            type: string
          description: >-
            Exact key_ ID of the submitting key. Older unattributed prompts do
            not match.
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
          description: Inclusive lower creation-time bound (RFC3339 with timezone).
        - name: created_before
          in: query
          schema:
            type: string
            format: date-time
          description: Exclusive upper creation-time bound (RFC3339 with timezone).
        - name: metadata
          in: query
          style: deepObject
          explode: true
          schema:
            type: object
            maxProperties: 16
            additionalProperties:
              type: string
              maxLength: 512
          description: >-
            Exact AND matches, e.g. metadata[customer]=Acme. Keys up to 64
            bytes; values up to 512 bytes.
      responses:
        '200':
          description: A page of prompts
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                required:
                  - data
                  - next_cursor
                properties:
                  data:
                    type: array
                    maxItems: 100
                    items:
                      $ref: '#/components/schemas/Prompt'
                  next_cursor:
                    type:
                      - string
                      - 'null'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    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
    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'
    Metadata:
      type: object
      maxProperties: 16
      additionalProperties:
        type: string
        maxLength: 512
      propertyNames:
        minLength: 1
        maxLength: 64
      example:
        customer: acme
        environment: production
    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
    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>.

````