Tools API

The six calls behind every tool. Rate limits are the anonymous allowance; signing in or using a token raises it, and a tool's cost counts against the limit.

Over a limit is 429 with Retry-After; every answer also carries RateLimit-* headers. Errors are RFC 9457 problems with a stable code.

Every tool is described by a machine-readable descriptor (inputs as JSON Schema, file limits, how it runs, who may call it).

• /api/v1/tools: the registry (filter with ?family=, ?q=, ?api=true)
• /api/v1/tools/{id} and /api/v1/tools/{id}/schema: one tool
• /api/v1/openapi.json: OpenAPI 3.1, generated from the descriptors

curl -X POST https://openvibe.tools/api/v1/tools/jsonminify/run \
  -H 'Content-Type: application/json' \
  -d '{"input":{"text":"{ \"a\": 1 }"}}'
# → {"state":"succeeded","tool":"jsonminify","result":{"text":"{\"a\":1}"},"took_ms":3}

File tools take multipart/form-data (file parts plus an input JSON part). Work that outlasts wait_ms answers 202 with a job: follow it at /api/v1/jobs/{id}/events (server-sent events) and download results from /api/v1/jobs/{id}/files/{n}. Send an Idempotency-Key header to make retries safe.

const { createClient } = require('openvibe-sdk/core');
const { createToolsClient } = require('openvibe-sdk/tools');
const tools = createToolsClient(createClient({}));
const out = await tools.run('jsonminify', { text: '{ "a": 1 }' });
const job = await tools.run('png', { format: 'png' }, { files: [fileBlob] });
const done = await job.wait();   // any tool, sync or job

The SDK is openvibe-sdk (this site pins v0.67.0). It retries on 429 after Retry-After and generates idempotency keys for you.

• Anonymous: most tools, on the lowest quota tier, per address. Tools that handle files people should not share anonymously (audio, PDF) need a browser session or a token.
• Apps and services: a token from OpenVibe.Network for audience openvibe.tools with tools.tool.run (developer sandbox apps get it by default) raises the tier.
• Network probes (port checks, ping, latency) need tools.net.probe, granted to partners only. The YouTube downloader has no API.
• Every answer carries RateLimit-* headers; over the limit is 429 with Retry-After. Errors are RFC 9457 problems with a stable code.