ToolList tools.tool-list@1

Generated at from openvibe-contracts v0.114.0 and openvibe-sdk v0.35.1.

Version
1.0.0
Owner
tools
Visibility
public
Status
active
Compatibility
backward
Decision
ADR-027
Schema
https://openvibe.network/contracts/tools/tool-list.v1.json

The answer of GET /api/v1/tools on openvibe.tools (capability tools.tool.read; ADR-027): every tool's descriptor (tools.tool@1), with input and output schemas in the { $ref } form (GET /api/v1/tools/:id has them embedded). Filters: ?family=, ?execution=client|sync|job, ?api=true|false, ?status=, ?q= (every word must appear in the id, name, summary or keywords); family, execution and status take comma lists. An unknown execution or status value, or an api that is not true or false, is 400 tools.query.invalid. Every listed tool has one of the descriptor's statuses: there is no planned status, so planned placeholders are not tools and are not listed, and neither are mirrors (GET /api/v1/tools/:id answers 404 tools.tool.not_found for both, with a detail saying why). Cacheable (ETag); updated_at changes when any descriptor does.

Fields

FieldTypeRequiredDescriptionConstraints
toolstools.toolyes
countintegeryesThe number of tools in this answer.
  • minimum 0
updated_atstringyes
  • format date-time
familiesarray of objectThe families of the tools in this answer.
  • items: no other fields
families[].idstringyes
  • pattern ^[a-z][a-z0-9-]{1,39}$
families[].namestringyes
  • minLength 1
  • maxLength 80
families[].countintegeryes
  • minimum 0

Examples

From the contract's own test fixtures: valid ones validate, rejected ones must fail.

Valid: empty-filter
{
  "tools": [],
  "count": 0,
  "updated_at": "2026-09-23T21:00:00.000Z"
}
Valid: four-tools
{
  "tools": [
    {
      "id": "png",
      "family": "img",
      "name": "PNG Converter",
      "summary": "Convert JPG, WebP, AVIF, HEIC, GIF, BMP, TIFF and more to PNG.",
      "keywords": [
        "jpg to png",
        "webp to png",
        "heic to png",
        "convert image to png"
      ],
      "status": "stable",
      "execution": "job",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/png/run",
        "job": {
          "type": "img.process",
          "operation": "convert",
          "preset": {
            "format": "png"
          }
        },
        "legacy": [
          "POST /api/process",
          "POST /api/process/direct"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/png/schema#/$defs/input"
      },
      "files": {
        "min": 1,
        "max": 1,
        "accept": [
          "image/*"
        ],
        "maxBytes": 52428800
      },
      "output": {
        "kind": "file",
        "mime": [
          "image/png"
        ]
      },
      "limits": {
        "timeoutMs": 120000,
        "maxPixels": 100000000
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-job",
      "cost": 5,
      "egress": false,
      "hosts": [
        "png.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/png"
    },
    {
      "id": "dns",
      "family": "net",
      "name": "DNS Lookup",
      "summary": "Look up A, AAAA, MX, TXT, NS, CNAME and other records for a domain.",
      "keywords": [
        "dns lookup",
        "mx record lookup",
        "txt record check",
        "nslookup online"
      ],
      "status": "stable",
      "execution": "sync",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/dns/run",
        "job": null,
        "legacy": [
          "GET /api/net/dns/:target"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/dns/schema#/$defs/input"
      },
      "files": null,
      "output": {
        "kind": "json",
        "schema": {
          "$ref": "https://openvibe.tools/api/v1/tools/dns/schema#/$defs/output"
        }
      },
      "limits": {
        "timeoutMs": 10000,
        "maxInputBytes": 1024,
        "perTargetPerMinute": 30
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-fetch",
      "cost": 1,
      "egress": true,
      "hosts": [
        "dns.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/dns"
    },
    {
      "id": "port",
      "family": "net",
      "name": "Port Checker",
      "summary": "Check whether TCP ports on a host are open.",
      "keywords": [
        "open port checker",
        "port scanner"
      ],
      "status": "beta",
      "execution": "sync",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/port/run",
        "job": null,
        "legacy": [
          "GET /api/net/port/:target"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/port/schema#/$defs/input"
      },
      "files": null,
      "output": {
        "kind": "json",
        "schema": {
          "$ref": "https://openvibe.tools/api/v1/tools/port/schema#/$defs/output"
        }
      },
      "limits": {
        "timeoutMs": 15000,
        "perTargetPerMinute": 6
      },
      "auth": {
        "anonymous": false,
        "capability": "tools.net.probe"
      },
      "quotaClass": "tools-probe",
      "cost": 5,
      "egress": true,
      "hosts": [
        "port.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/port"
    },
    {
      "id": "yt",
      "family": "media",
      "name": "YouTube Downloader",
      "summary": "Save a YouTube video or its audio.",
      "status": "stable",
      "execution": "job",
      "api": false,
      "run": null,
      "input": null,
      "files": null,
      "output": {
        "kind": "file",
        "mime": [
          "video/mp4",
          "audio/mpeg"
        ]
      },
      "limits": {
        "timeoutMs": 900000,
        "maxDurationSec": 3600,
        "perTargetPerMinute": 20
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-download",
      "cost": 50,
      "egress": true,
      "hosts": [
        "youtube-downloader.openvibe.tools",
        "yt.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/yt"
    }
  ],
  "count": 4,
  "updated_at": "2026-09-23T21:00:00.000Z",
  "families": [
    {
      "id": "img",
      "name": "Image Tools",
      "count": 1
    },
    {
      "id": "net",
      "name": "Network Tools",
      "count": 2
    },
    {
      "id": "media",
      "name": "Media",
      "count": 1
    }
  ]
}
Rejected: bad-descriptor
{
  "tools": [
    {
      "id": "png",
      "family": "img",
      "name": "PNG Converter",
      "summary": "Convert JPG, WebP, AVIF, HEIC, GIF, BMP, TIFF and more to PNG.",
      "status": "stable",
      "execution": "job",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/png/run",
        "job": {
          "type": "img.process",
          "operation": "convert",
          "preset": {
            "format": "png"
          }
        },
        "legacy": [
          "POST /api/process",
          "POST /api/process/direct"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/png/schema#/$defs/input"
      },
      "files": {
        "min": 1,
        "max": 1,
        "accept": [
          "image/*"
        ],
        "maxBytes": 52428800
      },
      "output": {
        "kind": "file",
        "mime": [
          "image/png"
        ]
      },
      "limits": {
        "timeoutMs": 120000,
        "maxPixels": 100000000
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-job",
      "cost": 5,
      "egress": false,
      "hosts": [
        "png.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/png"
    },
    {
      "id": "dns",
      "family": "net",
      "name": "DNS Lookup",
      "summary": "Look up A, AAAA, MX, TXT, NS, CNAME and other records for a domain.",
      "status": "stable",
      "execution": "sync",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/dns/run",
        "job": null,
        "legacy": [
          "GET /api/net/dns/:target"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/dns/schema#/$defs/input"
      },
      "files": null,
      "output": {
        "kind": "json",
        "schema": {
          "$ref": "https://openvibe.tools/api/v1/tools/dns/schema#/$defs/output"
        }
      },
      "limits": {
        "timeoutMs": 10000,
        "maxInputBytes": 1024,
        "perTargetPerMinute": 30
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-fetch",
      "cost": 1,
      "egress": true,
      "hosts": [
        "dns.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/dns"
    },
    {
      "id": "port",
      "family": "net",
      "name": "Port Checker",
      "summary": "Check whether TCP ports on a host are open.",
      "status": "beta",
      "execution": "sync",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/port/run",
        "job": null,
        "legacy": [
          "GET /api/net/port/:target"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/port/schema#/$defs/input"
      },
      "files": null,
      "output": {
        "kind": "json",
        "schema": {
          "$ref": "https://openvibe.tools/api/v1/tools/port/schema#/$defs/output"
        }
      },
      "limits": {
        "timeoutMs": 15000,
        "perTargetPerMinute": 6
      },
      "auth": {
        "anonymous": false,
        "capability": "tools.net.probe"
      },
      "quotaClass": "tools-probe",
      "cost": 5,
      "egress": true,
      "hosts": [
        "port.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/port"
    },
    {
      "id": "yt",
      "family": "media",
      "name": "YouTube Downloader",
      "summary": "Save a YouTube video or its audio.",
      "status": "stable",
      "execution": "job",
      "api": false,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/yt/run",
        "job": null
      },
      "input": null,
      "files": null,
      "output": {
        "kind": "file",
        "mime": [
          "video/mp4",
          "audio/mpeg"
        ]
      },
      "limits": {
        "timeoutMs": 900000,
        "maxDurationSec": 3600,
        "perTargetPerMinute": 20
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-download",
      "cost": 50,
      "egress": true,
      "hosts": [
        "youtube-downloader.openvibe.tools",
        "yt.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/yt"
    }
  ],
  "count": 4,
  "updated_at": "2026-09-23T21:00:00.000Z",
  "families": [
    {
      "id": "img",
      "name": "Image Tools",
      "count": 1
    },
    {
      "id": "net",
      "name": "Network Tools",
      "count": 2
    },
    {
      "id": "media",
      "name": "Media",
      "count": 1
    }
  ]
}
Rejected: no-count
{
  "tools": [
    {
      "id": "png",
      "family": "img",
      "name": "PNG Converter",
      "summary": "Convert JPG, WebP, AVIF, HEIC, GIF, BMP, TIFF and more to PNG.",
      "status": "stable",
      "execution": "job",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/png/run",
        "job": {
          "type": "img.process",
          "operation": "convert",
          "preset": {
            "format": "png"
          }
        },
        "legacy": [
          "POST /api/process",
          "POST /api/process/direct"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/png/schema#/$defs/input"
      },
      "files": {
        "min": 1,
        "max": 1,
        "accept": [
          "image/*"
        ],
        "maxBytes": 52428800
      },
      "output": {
        "kind": "file",
        "mime": [
          "image/png"
        ]
      },
      "limits": {
        "timeoutMs": 120000,
        "maxPixels": 100000000
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-job",
      "cost": 5,
      "egress": false,
      "hosts": [
        "png.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/png"
    },
    {
      "id": "dns",
      "family": "net",
      "name": "DNS Lookup",
      "summary": "Look up A, AAAA, MX, TXT, NS, CNAME and other records for a domain.",
      "status": "stable",
      "execution": "sync",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/dns/run",
        "job": null,
        "legacy": [
          "GET /api/net/dns/:target"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/dns/schema#/$defs/input"
      },
      "files": null,
      "output": {
        "kind": "json",
        "schema": {
          "$ref": "https://openvibe.tools/api/v1/tools/dns/schema#/$defs/output"
        }
      },
      "limits": {
        "timeoutMs": 10000,
        "maxInputBytes": 1024,
        "perTargetPerMinute": 30
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-fetch",
      "cost": 1,
      "egress": true,
      "hosts": [
        "dns.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/dns"
    },
    {
      "id": "port",
      "family": "net",
      "name": "Port Checker",
      "summary": "Check whether TCP ports on a host are open.",
      "status": "beta",
      "execution": "sync",
      "api": true,
      "run": {
        "method": "POST",
        "path": "/api/v1/tools/port/run",
        "job": null,
        "legacy": [
          "GET /api/net/port/:target"
        ]
      },
      "input": {
        "$ref": "https://openvibe.tools/api/v1/tools/port/schema#/$defs/input"
      },
      "files": null,
      "output": {
        "kind": "json",
        "schema": {
          "$ref": "https://openvibe.tools/api/v1/tools/port/schema#/$defs/output"
        }
      },
      "limits": {
        "timeoutMs": 15000,
        "perTargetPerMinute": 6
      },
      "auth": {
        "anonymous": false,
        "capability": "tools.net.probe"
      },
      "quotaClass": "tools-probe",
      "cost": 5,
      "egress": true,
      "hosts": [
        "port.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/port"
    },
    {
      "id": "yt",
      "family": "media",
      "name": "YouTube Downloader",
      "summary": "Save a YouTube video or its audio.",
      "status": "stable",
      "execution": "job",
      "api": false,
      "run": null,
      "input": null,
      "files": null,
      "output": {
        "kind": "file",
        "mime": [
          "video/mp4",
          "audio/mpeg"
        ]
      },
      "limits": {
        "timeoutMs": 900000,
        "maxDurationSec": 3600,
        "perTargetPerMinute": 20
      },
      "auth": {
        "anonymous": true,
        "capability": "tools.tool.run"
      },
      "quotaClass": "tools-download",
      "cost": 50,
      "egress": true,
      "hosts": [
        "youtube-downloader.openvibe.tools",
        "yt.openvibe.tools"
      ],
      "docs": "https://openvibe.tools/tool/yt"
    }
  ],
  "updated_at": "2026-09-23T21:00:00.000Z",
  "families": [
    {
      "id": "img",
      "name": "Image Tools",
      "count": 1
    },
    {
      "id": "net",
      "name": "Network Tools",
      "count": 2
    },
    {
      "id": "media",
      "name": "Media",
      "count": 1
    }
  ]
}

Validate

const contracts = require('openvibe-contracts');
contracts.validate('tools.tool-list@1', value);   // { valid, errors: [{ path, message }] }