Skip to content
All documentation

Quickstart

Updated
Reading time
3 min
Level
beginner
Needs
A Revoye Cloud account with a verified email address
On this page

Three requests: create a key, check that a model can answer, send a prompt. All you need is a Revoye Cloud account with a verified email address — sign up if you do not have one. There is nothing to install and no provider account or provider API key to connect.

1. Get a key

Sign in to the dashboard, open API keys, and create one.

The secret is shown once. Revoye Cloud stores only 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_API_KEY="revoye_sk_live_…"
export REVOYE_BASE_URL="https://cloudapi.revoye.com"

2. Check that something can answer

curl $REVOYE_BASE_URL/v1/status \
  -H "Authorization: Bearer $REVOYE_API_KEY"
{
  "agents": { "total": 6, "idle": 4, "busy": 2, "error": 0, "offline": 0 },
  "providers": [
    {
      "kind": "chatgpt",
      "enabled": true,
      "agents_idle": 2,
      "rate_limit_per_hour": 60,
      "used_this_hour": 14
    }
  ],
  "queue": { "depth": 0, "oldest_queued_at": null }
}

agents_idle: 2 on chatgpt means there is processing capacity for ChatGPT right now. Zeros are not errors — they describe capacity at this instant, and a job sent now simply waits in the queue. See GET /v1/status.

3. Send a prompt

curl $REVOYE_BASE_URL/v1/completions \
  -H "Authorization: Bearer $REVOYE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --max-time 660 \
  -d '{
    "prompt": "Summarise the CAP theorem in three sentences.",
    "provider": "chatgpt",
    "wait": true
  }'

Expect to wait — typically 20 to 90 seconds.

{
  "id": "job_01JAY7Q2K8XYZ3M4N5P6Q7R8S9",
  "status": "succeeded",
  "response": "The CAP theorem states that…",
  "provider": "chatgpt",
  "agent_id": "agt_01JAY7…",
  "agent_name": null,
  "conversation_ref": "<opaque string>",
  "attempts": 1,
  "queue_ms": 240,
  "run_ms": 18432,
  "created_at": "2026-09-18T09:14:02.000Z",
  "finished_at": "2026-09-18T09:14:21.000Z",
  "content_pruned_at": null,
  "metadata": {}
}

That is the whole quickstart.

What happens to a request

Revoye Cloud records every accepted request as a job before doing anything else, and returns its id. The job waits in a queue until a worker for the model you asked for is free, runs, and is retried automatically if an attempt fails or times out. With wait: true your connection is held until the job finishes; without it you collect the result later by id or by webhook. Nothing about your connection affects the job.

The same thing in Python

import os, uuid, httpx
 
client = httpx.Client(
    base_url=os.environ["REVOYE_BASE_URL"],
    headers={"Authorization": f"Bearer {os.environ['REVOYE_API_KEY']}"},
    timeout=660.0,          # the request is held until the job finishes
)
 
job = client.post(
    "/v1/completions",
    headers={"Idempotency-Key": str(uuid.uuid4())},
    json={"prompt": "Summarise the CAP theorem in three sentences.", "wait": True},
).json()
 
print(job["response"])

Note the client timeout. A default HTTP timeout of 10 or 30 seconds will abandon a perfectly healthy job. It will not cancel it — the job runs to completion and the result 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_BASE_URL}/v1/completions`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.REVOYE_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    prompt: "Summarise the CAP theorem in three sentences.",
    wait: true,
  }),
  signal: AbortSignal.timeout(660_000),
});
 
const job = await res.json();
console.log(job.response);

Next