AiRunRequest ai.run-request@1

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

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
credentialobjectRun with the person's own provider key (ai.credential@1) that this service stored, instead of a shared route: only that provider is called (no fallback), the result is never cached or taken from the cache, the shared paid budget is not spent, and the credential's own daily budget applies (429 quota.exceeded). Chat operations only (text, JSON, vision).
  • no other fields
credential.subjectstringyes
  • pattern ^usr_[0-9A-HJKMNP-TV-Z]{26}$

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
  }
}
Valid: with-credential
{
  "workflow": "live.viewers.line",
  "input": {
    "system": "s",
    "user": "u"
  },
  "credential": {
    "subject": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
  }
}
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 }] }