Skip to content
All documentation

Quickstart

Updated
Reading time
2 min
Level
beginner
Needs
A Revoye account with a paired device and at least one agent
On this page

Three requests: create a key, check that something is online, send a prompt. This page assumes you already have a Revoye account with Revoye Desk paired and at least one agent running in the extension. If you do not, set that up first — the API has nowhere to send work until you do.

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 something can answer

curl https://revoyeapi.degird.com/v1/status \
  -H "Authorization: Bearer $REVOYE_KEY"
{
  "devices": { "total": 1, "online": 1 },
  "agents": { "total": 3, "idle": 3, "busy": 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 }
}

devices.online: 1 and agents.idle: 3 means you are ready. Zeros are not errors — they are a description of your fleet right now. See status.

3. Send a prompt

curl https://revoyeapi.degird.com/v1/completions \
  -H "Authorization: Bearer $REVOYE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "prompt": "Summarise the CAP theorem in three sentences.",
    "provider": "chatgpt",
    "wait": true
  }'

Expect to wait. A browser is typing your prompt into ChatGPT and a model is answering.

{
  "id": "job_01JAY7Q2K8XYZ",
  "status": "succeeded",
  "response": "The CAP theorem states that…",
  "provider": "chatgpt",
  "agent_id": "agt_01JAY7…",
  "agent_name": "Agent 2",
  "conversation_ref": "https://chatgpt.com/c/6f0a…",
  "attempts": 1,
  "queue_ms": 240,
  "run_ms": 18432,
  "created_at": "2026-08-18T09:14:02Z",
  "finished_at": "2026-08-18T09:14:21Z",
  "metadata": {}
}

That is the whole quickstart.

The same thing in Python

import os, uuid, httpx
 
client = httpx.Client(
    base_url="https://revoyeapi.degird.com",
    headers={"Authorization": f"Bearer {os.environ['REVOYE_KEY']}"},
    timeout=300.0,          # the request is held while the browser works
)
 
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_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 the CAP theorem in three sentences.",
    wait: true,
  }),
  signal: AbortSignal.timeout(300_000),
});
 
const job = await res.json();
console.log(job.response);

Next