CodesTaskStartRequest codes.task-start-request@1

Generated at 2026-10-15 07:46:20 UTC from openvibe-contracts v0.177.0 and openvibe-sdk v0.44.0.

Version

1.0.0

Owner

codes

Visibility

first-party

Status

active

Compatibility

backward

Schema

https://openvibe.network/contracts/codes/task-start-request.v1.json

codes.task-start-request@1: the body of POST /api/v1/tasks on OpenVibe.Codes (capability codes.task.start). A first-party service (OpenVibe.Actor) starts a coding task for a person, named with X-OV-Subject: Codes runs it on that person's own machine through OpenVibe.Run (openvibe.codes/run, plan T16), in the project of their latest task there, so the person has used openvibe.codes/run once before a service can start one for them (else 409 codes.no_project). REPO is an https git URL with no credentials; REF a branch or tag to start from (default: the repository's default branch). PROMPT is the task. AGENT names one of Codes' agents (GET /harnesses), absent for Codes' router to pick. PERMISSION: edit (default; the agents edit files) or full (they may also run commands: tests, installs). PUSH asks for the change on a new branch (GitHub, with the machine's GITHUB_TOKEN; never the branch it started from), PULL_REQUEST also opens a pull request. IDEMPOTENCY_KEY: a repeat for the same person with the same key answers the first task (200, created false).

Fields

Examples

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

{
  "repo": "https://github.com/octocat/Hello-World",
  "ref": "master",
  "prompt": "Fix the failing test and run the suite.",
  "agent": "deepseek",
  "permission": "full",
  "push": true,
  "pull_request": true,
  "idempotency_key": "act_01M4XF00000000000000000000:step-2"
}

{
  "repo": "https://github.com/octocat/Hello-World",
  "prompt": "Add a line to the README."
}

{
  "repo": "https://github.com/octocat/Hello-World",
  "prompt": ""
}

{
  "repo": "https://user:[email protected]/octocat/Hello-World",
  "prompt": "x"
}

{
  "repo": "[email protected]:octocat/Hello-World.git",
  "prompt": "x"
}

{
  "repo": "https://github.com/octocat/Hello-World",
  "prompt": "x",
  "project": "prj_01M4XE52PGJDVR1KZ1AG9VYW3Q"
}

{
  "repo": "https://github.com/octocat/Hello-World",
  "prompt": "x",
  "permission": "root"
}

Validate

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