Create a prompt

Queue a prompt with its maximum authorized cost

curl --request POST \
  --url https://revise.io/api/v1/prompt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://revise.io/api/v1/prompt"

payload = {
    "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"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'}
  })
};

fetch('https://revise.io/api/v1/prompt', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://revise.io/api/v1/prompt",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://revise.io/api/v1/prompt"

	payload := strings.NewReader("{\n  \"prompt\": \"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon.\",\n  \"document_access\": \"read\",\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"development\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://revise.io/api/v1/prompt")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon.\",\n  \"document_access\": \"read\",\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"development\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://revise.io/api/v1/prompt")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon.\",\n  \"document_access\": \"read\",\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"development\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "conversation_id": "<string>",
  "previous_prompt_id": "<string>",
  "status": "queued",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "conversation_expires_at": "2023-11-07T05:31:56Z",
  "message": {
    "role": "assistant",
    "content": "<string>",
    "incomplete": true,
    "citations": [
      {
        "id": "<string>",
        "url": "<string>",
        "title": "<string>",
        "startIndex": 123,
        "endIndex": 123
      }
    ]
  },
  "continuation": {
    "reasoning_state": "new",
    "history_compacted": true,
    "reason": "<string>"
  },
  "artifacts": [
    {
      "id": "<string>",
      "format": "docx",
      "filename": "<string>",
      "content_type": "<string>",
      "variant": "tracked_changes",
      "sha256": "<string>",
      "bytes": 123,
      "download_url": "<string>",
      "input_eligible": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "prompt_id": "<string>",
      "conversion_id": "<string>",
      "encryption": {
        "format": "jwe",
        "alg": "RSA-OAEP-256",
        "enc": "A256GCM",
        "key_id": "<string>"
      },
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "usage": {
    "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": {
    "customer": "acme",
    "environment": "production"
  },
  "inference": {
    "provider": "openai",
    "model": "<string>",
    "billing": "revise"
  },
  "limits": {
    "max_platform_cost_usd": "0.050000000",
    "max_inference_cost_usd": "0.050000000",
    "max_seconds": 123
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "api_key_id": "<string>",
  "output_encrypted": true,
  "comments": [
    {
      "root": {},
      "replies": [
        {}
      ],
      "anchor": {},
      "relatedSuggestionIds": [
        "<string>"
      ]
    }
  ],
  "changes": [
    {
      "id": "<string>",
      "kind": "<string>",
      "blockIds": [
        "<string>"
      ],
      "commentThreadId": "<string>"
    }
  ],
  "content_expires_at": "2023-11-07T05:31:56Z",
  "content_deleted_at": "2023-11-07T05:31:56Z",
  "retention": {
    "delete_after_webhook_id": "<string>"
  },
  "incomplete": true,
  "stop_reason": "spending_limit"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

POST

prompt

Queue a prompt with its maximum authorized cost

curl --request POST \
  --url https://revise.io/api/v1/prompt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "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"
  }
}
'

import requests

url = "https://revise.io/api/v1/prompt"

payload = {
    "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"
    }
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'}
  })
};

fetch('https://revise.io/api/v1/prompt', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://revise.io/api/v1/prompt",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://revise.io/api/v1/prompt"

	payload := strings.NewReader("{\n  \"prompt\": \"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon.\",\n  \"document_access\": \"read\",\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"development\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://revise.io/api/v1/prompt")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon.\",\n  \"document_access\": \"read\",\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"development\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://revise.io/api/v1/prompt")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"Rewrite this paragraph in a clear, professional tone: We got your request and will get back to you soon.\",\n  \"document_access\": \"read\",\n  \"metadata\": {\n    \"customer\": \"acme\",\n    \"environment\": \"development\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "conversation_id": "<string>",
  "previous_prompt_id": "<string>",
  "status": "queued",
  "created_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "conversation_expires_at": "2023-11-07T05:31:56Z",
  "message": {
    "role": "assistant",
    "content": "<string>",
    "incomplete": true,
    "citations": [
      {
        "id": "<string>",
        "url": "<string>",
        "title": "<string>",
        "startIndex": 123,
        "endIndex": 123
      }
    ]
  },
  "continuation": {
    "reasoning_state": "new",
    "history_compacted": true,
    "reason": "<string>"
  },
  "artifacts": [
    {
      "id": "<string>",
      "format": "docx",
      "filename": "<string>",
      "content_type": "<string>",
      "variant": "tracked_changes",
      "sha256": "<string>",
      "bytes": 123,
      "download_url": "<string>",
      "input_eligible": true,
      "expires_at": "2023-11-07T05:31:56Z",
      "prompt_id": "<string>",
      "conversion_id": "<string>",
      "encryption": {
        "format": "jwe",
        "alg": "RSA-OAEP-256",
        "enc": "A256GCM",
        "key_id": "<string>"
      },
      "deleted_at": "2023-11-07T05:31:56Z"
    }
  ],
  "usage": {
    "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": {
    "customer": "acme",
    "environment": "production"
  },
  "inference": {
    "provider": "openai",
    "model": "<string>",
    "billing": "revise"
  },
  "limits": {
    "max_platform_cost_usd": "0.050000000",
    "max_inference_cost_usd": "0.050000000",
    "max_seconds": 123
  },
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  },
  "api_key_id": "<string>",
  "output_encrypted": true,
  "comments": [
    {
      "root": {},
      "replies": [
        {}
      ],
      "anchor": {},
      "relatedSuggestionIds": [
        "<string>"
      ]
    }
  ],
  "changes": [
    {
      "id": "<string>",
      "kind": "<string>",
      "blockIds": [
        "<string>"
      ],
      "commentThreadId": "<string>"
    }
  ],
  "content_expires_at": "2023-11-07T05:31:56Z",
  "content_deleted_at": "2023-11-07T05:31:56Z",
  "retention": {
    "delete_after_webhook_id": "<string>"
  },
  "incomplete": true,
  "stop_reason": "spending_limit"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

This call returns an admission receipt. Poll the get endpoint until work stops, then download the artifacts. See job lifecycle.

TypeScript

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" });

Authorizations

Authorization

string

header

required

Revise API key from https://revise.io/console/api-keys. Send Authorization: Bearer .

Headers

Idempotency-Key

string

required

Required string length: 1 - 200

Body

application/json

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.

prompt

string

required

Required string length: 1 - 1048576

document_access

enum<string>

default:read

Available options:

read,

comment,

edit

previous_prompt_id

string

inputs

object[]

Maximum array length: 1

Option 1
Option 2

Show child attributes

export_document

boolean

limits

object

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.

Show child attributes

Example:

{
  "max_platform_cost_usd": "2.000000000",
  "max_inference_cost_usd": "3.000000000",
  "max_seconds": 900
}

inference

object

Show child attributes

metadata

object

Show child attributes

Example:

{
  "customer": "acme",
  "environment": "production"
}

output_encryption

object

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.

Show child attributes

response_options

object

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.

Show child attributes

retention

object

Show child attributes

Response

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.

string

required

conversation_id

string

required

previous_prompt_id

string | null

required

status

enum<string>

required

Available options:

queued,

running,

paused,

succeeded,

failed,

cancelled

created_at

string<date-time>

required

completed_at

string<date-time> | null

required

conversation_expires_at

string<date-time> | null

required

message

object | null

required

Show child attributes

continuation

object

required

Show child attributes

artifacts

object[]

required

Show child attributes

usage

object | null

required

Customer-facing settled charges and usage. Supplier costs, margins and internal reconciliation diagnostics are not exposed. Historical charges are never recalculated using current prices.

Show child attributes

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

object

required

Show child attributes

Example:

{
  "customer": "acme",
  "environment": "production"
}

inference

object

required

Show child attributes

limits

object

required

Show child attributes

error

object | null

required

Show child attributes

api_key_id

string | null

required

Non-secret ID of the key that originally submitted this prompt; null when not recorded. Idempotent retries preserve the original key.

output_encrypted

boolean

required

True disables continuation and reuse. Artifacts are encrypted for the supplied public key.

comments

object[]

Omitted when disabled by the stored response_options. Otherwise returns the existing native schema.

Show child attributes

changes

object[]

Omitted when disabled by the stored response_options. Otherwise returns the existing native schema.

Show child attributes

content_expires_at

string<date-time> | null

24 hours after terminal completion. Result content and new continuation become unavailable at this deadline.

content_deleted_at

string<date-time> | null

retention

object

Show child attributes

incomplete

boolean

True when the request returned a partial result.

stop_reason

enum<string>

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.

Available options:

spending_limit,

time_limit

Getting started

Guides

REST reference

TypeScript

Authorizations

Headers

Body

Response

​TypeScript

Authorizations

Headers

Body

Response

TypeScript