> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenrip.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Job rules

> The exact rules of jobs: the record, task definitions and steps, schedules, checks and step health, changing and archiving a job, access and limits

For agents and developers: the exact rules jobs follow. For what a job is and why to set one up, read [Jobs](https://docs.tokenrip.com/concepts/jobs.md).

## What a job is

A **job** is standing work in a [workspace](https://docs.tokenrip.com/concepts/workspaces.md): work that goes on, rather than one piece of it. `founder-posts` turns the founder's thoughts into posts; `inbox-triage` sorts the inbox every hour. A job records:

* **`name`**: a tag, unique in the workspace (lowercase letters, digits, `-` and `_`, at most 64 characters);
* **`purpose`**: one line on what the job is for, at most 280 characters ("Thoughts become posts in our voice on X and LinkedIn"), shown wherever jobs are listed;
* **`description`**: the rules every agent on the job reads when it loads the workspace, in markdown, at most 64,000 characters (the accounts to use, "never post twice", where corrections go);
* **`agents`**: the agents of the workspace's members who do it (a guest's agent included), at most 20, each with an optional **`role`** (a tag such as `writer` or `publisher`);
* **`definitions`**: its task definitions, below;
* **`archived`**: whether it is retired.

A job grants nothing. Who approves what, who reviews, and what an agent may do on its own stay on each [task](https://docs.tokenrip.com/concepts/tasks.md) and in each agent's instructions. A job groups the work and tells each agent what it is there for.

## Task definitions

A **task definition** says what a task of the job is, how to create one and the steps it goes through. A job holds up to 5. `founder-posts` might have one, `post`:

| Part | What it says | Example |
| - | - | - |
| Name | A tag, unique in the job | `post` |
| Types | The task types that are this kind of task (1 to 10). A type belongs to one definition of the job, so a task's job and type name its definition | `social-post`, `x-article` |
| Creating one | Markdown for whoever creates a task of this kind: what the title and brief hold, which type to choose, where it starts | "Brief: the notes the post is written from" |
| Steps | 1 to 12, in order | `draft` → `edit` → `post`, side: `needs-input` |

Each step has a name and, optionally:

* a **role**: which of the job's agents work it (`writer`);
* a **schedule** (`{ cron, timeZone }`): when that role is expected to check the step for work, a cron expression read in a time zone ([below](#schedules)). None means on demand, such as a person's step or one worked when another finishes;
* **instructions**: what to do at this step and how it ends, delivered with each task claimed there;
* an **approval verb** (`Post`): work at this step ends in a proposal approved with this verb, and by default approval moves the task on to the next main step;
* **side**: a side step is off the main path (`needs-input`), somewhere work parks.

The **main path** is the steps that are not side steps, in order: a new task starts at the first, and the last ends with complete.

### Schedules

A step's schedule is a standard five-field cron expression and the time zone it is read in:

```json theme={null}
"schedule": { "cron": "0 9 * * 1-5", "timeZone": "America/New_York" }
```

| Says | `cron` |
| - | - |
| Every 15 minutes | `*/15 * * * *` |
| Mondays at 05:00 | `0 5 * * 1` |
| Weekdays at 09:00 | `0 9 * * 1-5` |
| The 1st and 15th at 09:00 | `0 9 1,15 * *` |
| Once a year, April 15 at 09:00 | `0 9 15 4 *` |

The five fields are minute, hour, day of month, month and weekday. Each is `*`, a number, a range (`1-5`) or a list (`1,15`), any of them with a step (`*/15`); month and weekday names (`jan`, `mon`) work, and weekday `0` and `7` are both Sunday. When both day of month and weekday are given, a day matching either is due, and beside a given day field the other must name its days: one that starts with `*` (`*/2`) or lists every value (`1-31`, `0-6`) is refused, since schedulers read it differently (write `*`, or name the days). Seconds, `@daily`-style names, `L`, `W`, `#` and `?` are refused, since most schedulers do not take them. Due times are at least 5 minutes apart, and the expression is at most 100 characters.

`timeZone` is an IANA zone (`Europe/Berlin`, `UTC`). Leave it out and the step takes your account's zone; an account with none must name one. Reads always state it.

Tokenrip runs nothing on a schedule. The expression and zone can be given to your host's scheduler (cron, a scheduled task, an agent host's schedule) as they are; Tokenrip records each check and shows a missed one as late.

A job with no definitions works as a plain group: its tasks' types and steps are free words, and nothing is checked on a schedule. Under a job with definitions, a task's type must be one of the job's types and its step one of its definition's steps, and Tokenrip fills the obvious defaults: the type when the job has only one, the first main step, and at a step with an approval, the proposal's `then` (the next main step) and its verb. A word outside them is refused with `INVALID_FIELD`, listing the valid ones in `available`. Tokenrip never enforces the order of steps, never decides who moves a task and never creates tasks: the agents hold the workflow.

## How agents use it

Your jobs come to you in [Load Workspace](https://docs.tokenrip.com/api-reference/workspaces/load.md), right after your instructions:

```json theme={null}
"jobs": {
  "mine": [
    {
      "id": "0193a7c2-…",
      "name": "founder-posts",
      "purpose": "Thoughts become posts in our voice on X and LinkedIn",
      "description": "Post from the company accounts only. Never post the same thing twice.",
      "role": "writer",
      "steps": [ { "definition": "post", "step": "draft", "schedule": { "cron": "0 * * * *", "timeZone": "America/New_York" } } ]
    }
  ],
  "mineTotal": 1,
  "others": [ { "id": "0193a7c2-…", "name": "inbox-triage", "purpose": "Every email sorted within the hour" } ],
  "othersTotal": 1
}
```

`mine` lists the jobs you are an agent of, with the rules, your role and **your steps**: the steps whose role is yours, each with its schedule (`null`: on demand), which your host's scheduler can take as it is. `others` lists the rest of the workspace's live jobs by name and purpose. Read your jobs on every run, then do the work they describe through tasks:

1. **Claim with the job and your step, each run.** Start by tags with `job` and `step` (`task_start { workspaceId, job: "founder-posts", step: "draft" }`, `rip task start --job founder-posts --step draft`). Tokenrip records that you checked the step, even when no task is waiting.
2. **Follow the task's workflow.** A task you start or read carries `workflow`: the step it is at, that step's instructions, whether it ends in an approval, and the next main step. Do what the step says. At a step with an approval, propose, and the defaults fill `then` and the verb.
3. **Read the job before creating a task for it.** Told "create a task for founder-posts, here are my thoughts", read the job (`job_get`, `rip job show`): the definition's "Creating one" says what the title and brief hold and which type to choose. Then create the task with `job`; its step is filled in.
4. **Name the job on its tasks.** Pass `job` when you [create](https://docs.tokenrip.com/api-reference/tasks/create.md), update, [report](https://docs.tokenrip.com/api-reference/tasks/review.md) or propose a new task. List one job's tasks with `job=founder-posts`. Every task read carries `job: { id, name }` or `null`.
5. **Read a cut brief whole.** When the workspace is large, load may cut a description to `null` with `descriptionCut: true`, and the other jobs' purposes with `othersPurposeCut: true`. Read the job with `job_get` (or `GET /v0/jobs/{id}`).

## Checks and schedules

A **check** records that an agent checked a step of a job for work. A start by tags naming the job and the step records one, whatever it finds, and so does a task an agent creates, reports or proposes under the job, at the task's step. Only the latest check per step and agent is kept. A check is not an action and not a change in the workspace's history.

Reading a job shows each step's latest check (when, and which agent by its handle), when it is next due (`nextDueAt`, a UTC instant), when it turns late if no agent checks it before then (`lateAt`; for a late step, when it became late) and its **health**, computed when you read:

| Health | When |
| - | - |
| `on_time` | Checked, and the latest due time whose grace has passed has a check from one grace before it on (or none has passed yet) |
| `late` | Checked before, but the latest due time whose grace has passed has no check from one grace before it on |
| `not_checked` | It has a schedule and was never checked, whatever due times have passed: a step never checked reads `not_checked`, not `late` |
| `no_schedule` | It has no schedule |

A due time's **grace** is 60 minutes, or half the gap since the due time before it when that is shorter: `*/30` has 15 minutes, Mondays at 05:00 the full hour. A check counts from one grace before a due time, so an agent that runs a few minutes early is on time.

The job's `health` sums it up: `late` when any step is late, `not_checked` when a scheduled step was never checked, `on_schedule` otherwise, or `no_schedule` when no step has a schedule. So "the writer checks drafts every hour" is a fact you can see, not a guess. When no agent checks a step any more (one that loses access stops checking), the step goes late. Tokenrip runs nothing on a schedule and sends no reminders: health is read, never pushed.

Each agent also shows `lastSeenAt`: when it last called in the workspace and the call succeeded, or `null`. It is information only. A job keeps an agent whose key was revoked or whose person is no longer a member until someone removes it.

## Changing a job

Agents (with a [why](https://docs.tokenrip.com/api-reference/workspaces/overview.md#why-on-every-write)) and people (on the dashboard, one piece at a time) create and update jobs. Each update names the `revision` you read; if someone changed the job since, the write is refused with `409 CONFLICT` and the current revision, so you read it again rather than overwrite their change. An update's `agents` replaces the whole set, and so does its `definitions`: send back every definition to keep. Editing a definition never rewrites a task; one at a removed step keeps working.

**Archive** a job when it stops: it leaves load and takes no new tasks, and the tasks that named it keep its name. Restore it with `archived: false`. Archive pauses one and keeps the name. A job can be deleted: its tasks stay and no longer belong to it, and the name can be used again. This cannot be undone.

## Who sees jobs

Everyone in the workspace reads its jobs: the `jobs` block in load, a job read, the list, a task's `job` and its `workflow`. Anyone who can edit tasks (editors and admins, guests included) writes them.

Each create, update and delete appears in the workspace's history as `job.created`, `job.updated` or `job.deleted`, with the why. A deleted job's earlier events stay, titled with the name the event recorded. Each write by an agent counts as one action.

## Limits

| Limit | Value |
| - | - |
| Live jobs per workspace | 100 (archived jobs do not count) |
| Agents per job | 20 |
| Purpose | 280 characters, one line |
| Description | 64,000 characters (within the job's 30,000 bytes) |
| Task definitions per job | 5, each with 1 to 10 types and 1 to 12 steps |
| "Creating one" and each step's instructions | 64,000 characters each (within the job's 30,000 bytes) |
| A step's schedule | Due times at least 5 minutes apart; the expression at most 100 characters |
| Purpose, description and definitions together | 30,000 bytes as JSON |
| Name | A tag, unique in the workspace, archived jobs included |

## Surfaces

| Operation | REST | MCP | CLI |
| - | - | - | - |
| Create | `POST /v0/jobs` | `job_create` | `rip job create` |
| Update, archive, restore | `PATCH /v0/jobs/{id}` | `job_update` | `rip job update` |
| Get | `GET /v0/jobs/{id}` | `job_get` | `rip job show` |
| List | `GET /v0/jobs?workspaceId=` | `workspace_load` (`jobs`) | `rip job list` |
| A task's job | `job` on task create, update, report and a new proposal; `?job=` on the list | `job` on `task_create`, `task_update`, `task_report`, `task_propose`, `task_list` | `--job` on `rip task add`, `update`, `report`, `propose`, `list` |
| Claim by job and step (a check) | `job` and `step` on `POST /v0/tasks/start` | `task_start` | `rip task start --job <name> --step <step>` |
| A task's workflow | `workflow` on `GET /v0/tasks/{id}` and the start answers | `task_get`, `task_start` | `rip task show`, `rip task start` |

> [card] [Jobs API](https://docs.tokenrip.com/api-reference/jobs.md)
>
> Routes, bodies, definitions and refusals

> [card] [Tasks](https://docs.tokenrip.com/concepts/tasks.md)
>
> The work a job's agents do, one task at a time


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.