---
title: "codes.task@1 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/codes.task@1"
updated: null
---

# codes.task@1 · OpenVibe.Services

HTML: [codes.task@1 · OpenVibe.Services](https://openvibe.services/docs/contracts/codes.task@1)

# CodesTask `codes.task@1`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/v0.161.0).

An older major, still in the catalog. The current one is [`codes.task@2`](/docs/contracts/codes.task).

- Version: 1.1.0
- Owner: codes
- Visibility: first-party
- Status: active
- Compatibility: backward
- Schema: [`https://openvibe.network/contracts/codes/task.v1.json`](/docs/contracts/codes.task@1.json)

codes.task@1: a coding task on OpenVibe.Codes, as GET /api/v1/tasks/:id answers it (capability codes.task.read) and POST /api/v1/tasks creates it. STATE follows the OpenVibe.Run job that carries it: queued (waiting for one of the person's machines), placed, running, then succeeded, failed, cancelled or expired (no machine of theirs took it in time). URL is the task's page on openvibe.codes, where its owner follows it live. RESULT is present once it has ended: OK says whether the agents finished, SUMMARY what they said, FILES and PATCH the change (the patch at most 256 KiB, PATCH\_TRUNCATED when cut), PUSH where it went when asked, COST\_USD the model use on the person's own keys, DURATION\_MS the time on their machine. ERROR says why a task that never ran ended (Run refused it, or the job failed before a result).

## Fields

| Field | Type | Required | Description | Constraints |
| --- | --- | --- | --- | --- |
| `id` | string | yes | The Codes task id (tsk\_ + ULID). | - `pattern ^tsk_[0-9A-HJKMNP-TV-Z]{26}$` |
| `state` | enum | yes |  | - `one of "queued", "placed", "running", "succeeded", "failed", "cancelled", "expired"` |
| `repo` | string | yes |  | - `maxLength 300` |
| `ref` | string \| null |  |  | - `maxLength 200` |
| `agent` | string \| null |  |  | - `maxLength 41` |
| `url` | string | yes |  | - `pattern ^https://`<br>- `format uri` |
| `created_at` | string | yes |  | - `format date-time` |
| `updated_at` | string | yes |  | - `format date-time` |
| `error` | string \| null |  |  | - `maxLength 1000` |
| `result` | object |  |  | - `no other fields` |
| `result.ok` | boolean | yes |  |  |
| `result.agents` | array of string |  |  | - `maxItems 20`<br>- `items: maxLength 41` |
| `result.summary` | string |  |  | - `maxLength 4000` |
| `result.files` | array of object |  |  | - `maxItems 2000`<br>- `items: no other fields` |
| `result.files[].path` | string | yes |  | - `minLength 1`<br>- `maxLength 500` |
| `result.files[].added` | integer \| null |  |  | - `minimum 0` |
| `result.files[].removed` | integer \| null |  |  | - `minimum 0` |
| `result.patch` | string |  |  | - `maxLength 262144` |
| `result.patch_truncated` | boolean |  |  |  |
| `result.push` | object |  |  | - `no other fields` |
| `result.push.pushed` | boolean | yes |  |  |
| `result.push.branch` | string |  |  | - `maxLength 200` |
| `result.push.branch_url` | string |  |  | - `format uri` |
| `result.push.pull_request` | string |  |  | - `format uri` |
| `result.push.pull_request_error` | string |  |  | - `maxLength 500` |
| `result.push.reason` | string |  |  | - `maxLength 500` |
| `result.cost_usd` | number |  |  | - `minimum 0` |
| `result.duration_ms` | integer |  |  | - `minimum 0` |
| `result.error` | string |  |  | - `maxLength 1000` |
| `actor_ref` | object \| null |  | The OpenVibe.Actor task and step that started this coding task, when it came from Actor. |  |

## Examples

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

The fixtures that ship with the package are the current major's.

## Validate

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