ToolsRunRequest tools.run-request@1

Generated at from openvibe-contracts v0.33.0 and openvibe-sdk v0.5.0.

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

Body of POST /api/v1/tools/{id}/run on openvibe.tools (capability tools.tool.run, or tools.net.probe for network probes; ADR-027). JSON, or multipart/form-data like POST /api/v1/jobs: the text parts input (JSON text), wait_ms and idempotency_key, and uploaded files as file or files parts. The tool gets the uploaded files first, then the files references, in order; the count must fit the descriptor's files.min and files.max. input must match the tool's input schema (tools.tool@1 input). A job tool's job input is { ...input, ...run.job.preset, tool: run.job.operation } (the preset and the operation always win). The Idempotency-Key header wins over idempotency_key; ?wait_ms= on the query does the same as the field. Answers tools.run@1: 200 finished (succeeded, or failed with the tool's own error), 202 + Location while a job is queued or running, 200 + Idempotent-Replayed: true for a replay. Refusals are problem+json: 400 tools.run.invalid (not JSON, a bad field, wrong file count), 401 token.*, 403 capability.denied, 404 tools.tool.not_found, 404 tools.tool.not_runnable (api false: a page-only tool), 404 tools.run.file_not_found (a reference the caller cannot read), 409 tools.job.idempotency_conflict, 413 tools.file.too_large, 415 tools.file.unsupported_type (checked against the bytes), 422 tools.input.invalid (errors[] with JSON pointers), 429 quota.exceeded or tools.job.too_many_active (Retry-After), 503 tools.tool.unavailable.

Fields

FieldTypeRequiredDescriptionConstraints
inputobjectThe tool's parameters, matching its input schema. Default {}.
filesarray of one ofFiles that are already somewhere, instead of or besides uploaded parts.
  • maxItems 50
wait_msintegerJob tools: wait up to this long for the job to finish before answering (200 finished, else 202 with the job). Default 0. Inline tools always answer finished.
  • minimum 0
  • maximum 60000
idempotency_keystringJob tools: the same (caller, key) and request returns the same job; a different request under it is 409 tools.job.idempotency_conflict. Inline tools ignore it.
  • pattern ^[!-~]{8,200}$

Examples

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

Valid: chained-job-file
{
  "input": {
    "width": 512
  },
  "files": [
    {
      "job_id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
      "index": 0
    }
  ],
  "wait_ms": 20000,
  "idempotency_key": "resize-01JAB2C3"
}
Valid: empty
{}
Valid: inline-text
{
  "input": {
    "text": "{ \"a\": 1 }"
  }
}
Valid: media-object
{
  "input": {
    "tool_hint": "x"
  },
  "files": [
    {
      "media_id": "med_01JAB2C3D4E5F6G7H8J9K0MNPS"
    }
  ]
}
Rejected: both-reference-kinds
{
  "files": [
    {
      "media_id": "med_01JAB2C3D4E5F6G7H8J9K0MNPS",
      "job_id": "job_01JAB2C3D4E5F6G7H8J9K0MNPQ",
      "index": 0
    }
  ]
}
Rejected: input-array
{
  "input": [
    "a"
  ]
}
Rejected: job-type-field
{
  "type": "img.process",
  "input": {}
}
Rejected: short-idempotency-key
{
  "idempotency_key": "abc"
}
Rejected: url-reference
{
  "files": [
    {
      "url": "http://169.254.169.254/latest/meta-data"
    }
  ]
}
Rejected: wait-too-long
{
  "input": {},
  "wait_ms": 600000
}

Validate

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