> ## 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.

# Jobs

> Named standing work in a workspace, with the brief its agents read and the agents who do it, each with a role and how often it runs

## 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` writes and publishes three posts a week; `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);
* **`description`**: the standing brief its agents read, in markdown, at most 8,000 characters;
* **`agents`**: the agents of the workspace's internal members who do it (a guest's agent can't join a job), at most 20, each with an optional **`role`** (a tag such as `writer` or `publisher`) and an optional **`everyMinutes`**, how often it is expected to run (5 minutes to 30 days);
* **`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.

## 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", "description": "Three posts a week in our voice. Draft, then propose before posting.", "role": "writer", "everyMinutes": 60 }
  ],
  "mineTotal": 1,
  "others": [ { "id": "0193a7c2-…", "name": "inbox-triage" } ],
  "othersTotal": 1
}
```

`mine` lists the jobs you are an agent of, with the brief and your part in each; `others` lists the rest of the workspace's live jobs by name. Read your jobs on every run, then do the work they describe through tasks:

1. **Name the job on its tasks.** Pass `job: "founder-posts"` when you [create](https://docs.tokenrip.com/api-reference/tasks/create.md), update or [report](https://docs.tokenrip.com/api-reference/tasks/review.md) a task. List one job's tasks with `job=founder-posts`. Every task read carries `job: { id, name }` or `null`.
2. **Read a cut brief whole.** When the workspace is large, load may cut a description to `null` with `descriptionCut: true`. Read the job with `job_get` (or `GET /v0/jobs/{id}`).
3. **Adjust your own cadence.** If you should run more or less often, read the job, then update its `agents` with your new `everyMinutes` at the revision you read. Send the whole set: the agents you send replace the job's.

## 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) 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.

**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`. Jobs are never deleted, so a name stays taken by its archived job.

## Is each agent running?

Reading a job shows each agent's `lastSeenAt`, when it last called in the workspace and the call succeeded (a load counts, so a run with nothing to do still shows), and its `health` against its `everyMinutes`:

| Health | Meaning |
| - | - |
| `on_time` | Seen within 1.5 × `everyMinutes` |
| `late` | Not seen since then |
| `not_seen` | Never seen in this workspace |
| `no_schedule` | No `everyMinutes`: nothing is expected |
| `no_access` | Its key was revoked, or its person is no longer an internal member (they left, or are now a guest). The job keeps the agent until someone removes it |

Health is worked out when you read the job. Tokenrip runs nothing on a schedule and sends no reminders.

## Who sees jobs

Jobs are **internal**. An internal member of the workspace (its owner, or a member of its team) reads them, and writes them if they can edit tasks. A guest never sees one: their load has no `jobs`, a job read answers `404 JOB_NOT_FOUND`, the list is empty, and a task's `job` reads `null`.

Each create and update appears in the workspace's history as `job.created` or `job.updated`, internal only, with the why. 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 |
| Description | 8,000 characters |
| `everyMinutes` | 5 to 43,200 (30 days) |
| 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 and report; `?job=` on the list | `job` on `task_create`, `task_update`, `task_report`, `task_list` | `--job` on `rip task add`, `update`, `report`, `list` |

> [card] [Jobs API](https://docs.tokenrip.com/api-reference/jobs.md)
>
> Routes, bodies 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.