Using the HTTP API

https://api.relvo.si

export RELVO_API_URL="https://api.relvo.si"
export RELVO_API_KEY="rlv_..."

curl "$RELVO_API_URL/tools/project" \
  -H "Authorization: Bearer $RELVO_API_KEY"

const api = process.env.RELVO_API_URL;
const headers = { Authorization: `Bearer ${process.env.RELVO_API_KEY}` };

const response = await fetch(`${api}/tools/project`, { headers });
console.log(await response.json());

import os
import requests

api = os.environ["RELVO_API_URL"]
headers = {"Authorization": f"Bearer {os.environ['RELVO_API_KEY']}"}

response = requests.get(f"{api}/tools/project", headers=headers)
print(response.json())

curl "$RELVO_API_URL/tools/discover" \
  -H "Authorization: Bearer $RELVO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"query":"web search","limit":3}'

const found = await fetch(`${api}/tools/discover`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({ query: "web search", limit: 3 }),
}).then(response => response.json());
console.log(found.data.tools.map(tool => [tool.name, tool.price.description]));

found = requests.post(f"{api}/tools/discover", headers=headers,
                      json={"query": "web search", "limit": 3}).json()
print([(tool["name"], tool["price"]["description"]) for tool in found["data"]["tools"]])

curl "$RELVO_API_URL/tools/quote" \
  -H "Authorization: Bearer $RELVO_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"tool":"web_search","arguments":{"query":"content marketing"}}'

const request = { tool: "web_search", arguments: { query: "content marketing" } };
const { data: quote } = await fetch(`${api}/tools/quote`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(request),
}).then(response => response.json());
console.log(quote.priceVersion, quote.maximumChargeMicros);

request = {"tool": "web_search", "arguments": {"query": "content marketing"}}
quote = requests.post(f"{api}/tools/quote", headers=headers, json=request).json()["data"]
print(quote["priceVersion"], quote["maximumChargeMicros"])

IDEMPOTENCY_KEY=$(uuidgen)

curl "$RELVO_API_URL/tools/web_search" \
  -H "Authorization: Bearer $RELVO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Prefer: wait=25" \
  --data '{
    "tool": "web_search",
    "arguments": { "query": "content marketing" },
    "priceVersion": "<priceVersion from the quote>",
    "maximumChargeMicros": <maximumChargeMicros from the quote>
  }'

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID();
const { data: execution } = await fetch(`${api}/tools/${request.tool}`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, Prefer: "wait=25" },
  body: JSON.stringify({ ...request, priceVersion: quote.priceVersion, maximumChargeMicros: quote.maximumChargeMicros }),
}).then(response => response.json());
console.log(execution.id, execution.status);

import uuid

idempotency_key = str(uuid.uuid4())
execution = requests.post(
    f"{api}/tools/{request['tool']}",
    headers={**headers, "Idempotency-Key": idempotency_key, "Prefer": "wait=25"},
    json={**request, "priceVersion": quote["priceVersion"], "maximumChargeMicros": quote["maximumChargeMicros"]},
).json()["data"]
print(execution["id"], execution["status"])

curl "$RELVO_API_URL/tools/executions/$EXECUTION_ID" \
  -H "Authorization: Bearer $RELVO_API_KEY" \
  -H "Prefer: wait=25"

const active = ["queued", "running", "waiting"];
let current = execution;
while (active.includes(current.status)) {
  await new Promise(resolve => setTimeout(resolve, 5000));
  ({ data: current } = await fetch(`${api}/tools/executions/${current.id}`, {
    headers: { ...headers, Prefer: "wait=25" },
  }).then(response => response.json()));
}
console.log(current.status, current.chargedMicros, current.output);

import time

current = execution
while current["status"] in ("queued", "running", "waiting"):
    time.sleep(5)
    current = requests.get(f"{api}/tools/executions/{current['id']}",
                           headers={**headers, "Prefer": "wait=25"}).json()["data"]
print(current["status"], current["chargedMicros"], current["output"])

GET  /tools/project · project:read
  The team and project of the key

GET  /tools/usage · usage:read
  This month's requests and spend

GET  /tools · tools:read
  The catalog, whole or in pages of up to 50 (limit, offset)

POST /tools/discover · tools:read
  Tools ranked for one capability

GET  /tools/definition/{name} · tools:read
  One tool's full definition

GET  /tools/connections · tools:read
  The project's connections

POST /tools/quote · tools:read
  A free quote; starts nothing

POST /tools/{tool} · tools:execute
  Reserve the quoted amount and run the tool

POST /tools/executions/recover · tools:execute
  Find an execution by its idempotency key

GET  /tools/executions · executions:read
  Recent executions, newest first (status, tool, limit, before)

GET  /tools/executions/{id} · executions:read
  One execution with its output

GET  /tools/executions/{id}/context · executions:read
  An execution with a bounded result summary

POST /tools/executions/{id}/result · executions:read
  Read part of a large result

POST /tools/executions/{id}/cancel · tools:execute
  Ask an active execution to stop

GET  /tools/executions/{id}/artifacts/{artifactId}/download · executions:read
  A signed download URL for an artifact

POST /tools/upload · tools:execute
  Upload an input file