Skip to content
All documentation

Quickstart

Updated
Reading time
2 min
Level
beginner
Needs
A Revoye account with an active plan, and Revoye Desk connected if your plan uses it
On this page

Three steps: create a key, check that Revoye is ready, send a request. This page assumes you already have a Revoye account with an active plan. If your plan uses Revoye Desk, it should be installed on your device, connected to your account and signed in to your AI account — set that up first. With Revoye Cloud there is nothing to install.

1. Get a key

Sign in, open API keys, and create one.

The secret is shown once. Revoye stores a hash, so there is no endpoint that could show it to you again — if you lose it, rotate the key. It looks like this:

revoye_sk_live_3xQ8vP2mK9wR7tY4nL6jH1sD5fG0aZbC

Put it in your environment. Do not paste it into a file you will commit:

export REVOYE_KEY="revoye_sk_live_…"

2. Check that Revoye is ready

curl https://api.revoye.com/v1/status \
  -H "Authorization: Bearer $REVOYE_KEY"

Trimmed to the fields that matter here:

{
  "queue": { "depth": 0, "oldest_queued_at": null },
  "channels": {
    "cloud": { "available": true },
    "desk": { "available": true, "devices": { "online": 1 } }
  },
  "quota": {
    "cloud": { "used": 0, "limit": 1000000, "resets_at": "2026-11-13T00:00:00Z" },
    "desk": { "used": 0, "limit": 1000000, "resets_at": "2026-11-13T00:00:00Z" }
  }
}

channels lists each channel your plan includes, and available: true means it can process a request now. A channel that is not available is not an error — requests wait in your queue until it is. See status.

3. Send a request

curl https://api.revoye.com/v1/completions \
  -H "Authorization: Bearer $REVOYE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "Write a two-sentence product description for a handmade ceramic mug.",
    "channel": "auto",
    "wait": true
  }'

Most responses arrive in 3 to 90 seconds. The request is held open until the response is ready:

{
  "id": "job_01JAY7Q2K8XYZ",
  "status": "succeeded",
  "response": "Shaped by hand and glazed in small batches, this mug…",
  "channel": "cloud",
  "attempts": 1,
  "queue_ms": 240,
  "run_ms": 18432,
  "created_at": "2026-10-13T09:14:02Z",
  "finished_at": "2026-10-13T09:14:21Z",
  "metadata": {}
}

That is the whole quickstart. The full response object has a few more fields — POST /v1/completions lists them all.

The same thing in Python

import os, uuid, httpx
 
client = httpx.Client(
    base_url="https://api.revoye.com",
    headers={"Authorization": f"Bearer {os.environ['REVOYE_KEY']}"},
    timeout=300.0,          # the request is held until the response is ready
)
 
job = client.post(
    "/v1/completions",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={"prompt": "Summarise this customer review in one sentence: …", "wait": True},
).json()
 
print(job["response"])

Note the client timeout. A default HTTP timeout of 10 or 30 seconds will abandon a perfectly healthy request. It will not cancel it — the request is processed and the response waits at GET /v1/completions/{id} — but your code will not be there to see it.

The same thing in TypeScript

const res = await fetch(`${process.env.REVOYE_API_BASE}/v1/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REVOYE_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    prompt: "Summarise this customer review in one sentence: …",
    wait: true,
  }),
  signal: AbortSignal.timeout(300_000),
});
 
const job = await res.json();
console.log(job.response);

Next