AiRunRequest ai.run-request@1

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

Version
1.0.0
Owner
ai
Visibility
first-party
Status
active
Compatibility
backward
Decision
ADR-015
Schema
https://openvibe.network/contracts/ai/run-request.v1.json

Body of POST /api/v1/runs on OpenVibe.AI (capability ai.run.create; ADR-015). Runs the newest active version of a workflow (or the given active or deprecated version) on input that must match that workflow version's own input schema; per-workflow input and output schemas live in AI's registry (GET /api/v1/workflows/:key), not here. The token's ns claim limits which workflow namespaces may run (403 capability.namespace_denied). ?wait=ms waits for the result: 201 finished or served from cache, 202 still queued/running (poll GET /api/v1/runs/:id), 200 an idempotent replay. Errors are problem+json: 404 workflow.not_found, 409 workflow.inactive, 409 idempotency.conflict, 413 input.too_large, 422 input.invalid, 429 quota.exceeded or queue.full with Retry-After. The direct operations POST /api/v1/{chat,generate,summarize,classify,extract,enrich,embed} take the same fields (except workflow and version) with the input fields at the top level and run workflow ai.<op>. target (EntityRef): what the output is about, part of the cache scope and a run filter. attribution (EntityRef): what the spend is attributed to for quotas and usage. on_behalf_of (SubjectRef): the person or actor the caller acts for, part of the cache scope and per-actor quotas.

Fields

FieldTypeRequiredDescriptionConstraints
workflowstringyesWorkflow key, <namespace>.<name> (live.chat_reply, news.summarize_story, network.site_copy…).
  • pattern ^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)+$
  • maxLength 200
versionintegerPin a workflow version (active or deprecated). Omitted: the newest active version.
  • minimum 1
inputobjectWorkflow input; validated against the workflow version's input_schema. Default {}.
targetcommon.entity-ref
attributioncommon.entity-ref
on_behalf_ofidentity.subject-ref
idempotency_keystringSame (requester, key) returns the existing run; a different workflow or input under it is 409 idempotency.conflict. The Idempotency-Key header is used when this is absent.
  • pattern ^[A-Za-z0-9._:-]{8,128}$
optionsobject
  • no other fields
options.cachebooleanfalse skips the scoped cache lookup and store.
  • default true
options.debugbooleanKeep raw prompts and responses in the request log, only when AI runs with raw debug logging on.
  • default false

Examples

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

Valid: minimal
{
  "workflow": "network.site_copy",
  "input": {
    "sites": []
  }
}
Valid: news-summary
{
  "workflow": "news.summarize_story",
  "input": {
    "topic": "Transit strike",
    "sources": [
      {
        "source_type": "news.item",
        "source_id": "itm_42",
        "url": "https://example.com/a",
        "title": "Strike begins"
      }
    ]
  },
  "target": {
    "service": "news",
    "type": "story",
    "id": "sty_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  },
  "idempotency_key": "news:story:sty_01JAB2C3:v3",
  "options": {
    "cache": false
  }
}
Rejected: local-user-id
{
  "workflow": "live.chat_reply",
  "on_behalf_of": {
    "type": "user",
    "id": "42"
  }
}
Rejected: no-workflow
{
  "input": {
    "text": "hi"
  }
}
Rejected: unnamespaced-workflow
{
  "workflow": "summarize",
  "input": {}
}

Validate

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