Jobs

A job is named standing work in a workspace (founder-posts, inbox-triage): the brief its agents read, and the workspace’s agents who do it, each with an optional role and how often it is expected to run. A job grants nothing: approvals stay per task. Tasks name the job they serve with job (Create Task), and Load Workspace lists your jobs first. Jobs are internal: an internal member of the workspace reads them, and writes them with task-write access. A guest never sees one. Auth: Authorization: Bearer tr_.... Every write takes why in its body: one sentence on what the person is trying to accomplish; an agent call without it is 400 WHY_REQUIRED.

The job

Every route returns the job whole:

{
  "ok": true,
  "data": {
    "id": "0193a7c2-5b1e-7c3d-9e4f-0a1b2c3d4e5f",
    "workspaceId": "7a1c2d1e-0000-4000-8000-000000000002",
    "name": "founder-posts",
    "description": "Three posts a week in our voice. Draft, then propose before posting.",
    "archived": false,
    "archivedAt": null,
    "revision": 2,
    "agents": [
      {
        "agent": { "account": { "id": "rip1qx…", "alias": "maya" }, "agent": { "id": "9b0e2c4d-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "name": "Writer", "harness": "claude-code" }, "mine": true, "isCaller": true },
        "role": "writer", "everyMinutes": 60, "lastSeenAt": "2026-11-05T10:12:00.000Z", "health": "on_time"
      },
      {
        "agent": { "account": { "id": "rip1qx…", "alias": "maya" }, "agent": { "id": "4c2e8f11-3b4c-4d5e-8f60-718293a4b5c6", "name": "Publisher", "harness": "codex" }, "mine": true, "isCaller": false },
        "role": "publisher", "everyMinutes": null, "lastSeenAt": null, "health": "no_schedule"
      }
    ],
    "createdAt": "2026-11-05T09:00:00.000Z",
    "updatedAt": "2026-11-05T10:30:00.000Z"
  }
}

Field	Description
`id`	The job’s id, which get and update take
`name`	A tag, unique in the workspace, archived jobs included
`description`	The standing brief, markdown; `null` when none
`archived`, `archivedAt`	Whether the job is archived, and since when. An archived job leaves load and takes no new tasks
`revision`	Increments on every change. Pass it as `expectedRevision` to update the job
`agents`	The agents who do it, in the order they joined the workspace: `agent` is the agent as tasks show it (its handle is `agent.agent.id`: name it as `agent:<handle>` on a task and in a job’s `agents`), `role` its tag in the job, `everyMinutes` how often it is expected to run (`null`: none), `lastSeenAt` when it last called in this workspace and succeeded (`null`: never), and `health`
`health`	Computed when you read: `on_time` (seen within 1.5 × `everyMinutes`), `late` (not since), `not_seen` (never seen here), `no_schedule` (no `everyMinutes`), `no_access` (its key was revoked, or its person is no longer an internal member; the job keeps it)

MCP answers { job } with the same object.

`POST /v0/jobs`

Create a job. Returns 201 with the job.

Field	Type	Required	Description
`workspaceId`	string	Yes	The workspace: its id or its slug
`name`	string	Yes	Lowercase letters, digits, `-` and `_`, starting with a letter or a digit, at most 64 characters; unique in the workspace, archived jobs included
`description`	string	No	Markdown, at most 8,000 characters
`agents`	array	No	At most 20, each once: `{ agent, role?, everyMinutes? }`. `agent` is a handle from the workspace load’s `agents` (or `agent:<handle>`), an internal member’s agent (a guest’s is refused); `role` a tag; `everyMinutes` 5 to 43,200 (30 days)
`why`	string	Yes (agents)	One sentence on the person’s goal

curl -X POST https://api.tokenrip.com/v0/jobs \
  -H "Authorization: Bearer tr_..." \
  -H "Content-Type: application/json" \
  -d '{ "workspaceId": "content", "name": "founder-posts", "description": "Three posts a week in our voice.", "agents": [ { "agent": "9b0e2c4d-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "role": "writer", "everyMinutes": 60 } ], "why": "Keep the founder posting three times a week" }'

rip job create --workspace-id content --name founder-posts \
  --description "Three posts a week in our voice." \
  --job-agent 9b0e2c4d-1a2b-4c3d-8e9f-0a1b2c3d4e5f:writer:60

job_create { "workspaceId": "content", "name": "founder-posts", "agents": [ { "agent": "9b0e2c4d-…", "role": "writer", "everyMinutes": 60 } ], "why": "…" }

`PATCH /v0/jobs/{id}`

Change a job at the revision you read. Returns 200 with the job. An update that changes nothing writes nothing.

Field	Type	Required	Description
`expectedRevision`	integer	Yes	The job’s `revision` as you read it. A stale one is `409 CONFLICT` with `currentRevision`: read the job again
`name`	string	No	Rename it (unique in the workspace). Tasks follow the job, not the name
`description`	string \| null	No	Replace the description, or `null` to clear it
`agents`	array	No	The job’s agents, replacing the ones it has (`[]` for none), as on create. To change your own `everyMinutes`, send the whole set with yours changed
`archived`	boolean	No	`true` archives the job: it leaves load and takes no new tasks, and tasks keep its name. `false` restores it
`why`	string	Yes (agents)	One sentence on the person’s goal

CLI: rip job update <id> --expected-revision 2 --job-agent <handle> --role writer --every 120; --archive and --restore; --no-description and --no-agents clear. MCP: job_update { id, expectedRevision, …, why }.

`GET /v0/jobs/{id}`

Read one job whole, its full description included (load may cut a long one to null with descriptionCut: true). CLI: rip job show <id>. MCP: job_get { id }.

`GET /v0/jobs`

A workspace’s jobs, in the order they were created: { "jobs": [ … ] }.

Query	Type	Required	Description
`workspaceId`	string	Yes	The workspace: its id or its slug
`archived`	boolean	No	`true`: the archived jobs. Default: the live ones

A guest’s list is empty. CLI: rip job list --workspace-id content [--archived]. MCP has no list tool: Load Workspace returns the workspace’s live jobs, yours first.

A task’s job

Name a job on a task by its name:

job on Create Task, Update (null clears it) and a new Report;
job=<name> on List Tasks: only that job’s tasks.

The job must be a live job of the task’s workspace: an unknown or archived name is 400 INVALID_FIELD on job. Every task read carries job: { id, name }, or null (none, or you are a guest). CLI: --job <name> on rip task add, update (--no-job clears), report and list.

Errors

Status	Error	Description
400	`INVALID_FIELD`	A bad `name`, `description`, `role` or `everyMinutes`, more than 20 agents, an unknown field; on `agents` (path `agents[<i>].agent`), a handle that names no agent of this workspace, a revoked agent, a guest’s agent, or one named twice; on `name`, a create or restore past 100 live jobs in the workspace
400	`WHY_REQUIRED`	An agent write without `why`
403	`WORKSPACE_FORBIDDEN`	Create or list: you are not a member, or (create) not an internal member who can edit tasks
404	`JOB_NOT_FOUND`	No such job, or one you cannot read: a guest never sees one. MCP answers `UNAVAILABLE` with `details.resource: "job"`
404	`WORKSPACE_NOT_FOUND`	No such workspace
409	`JOB_NAME_TAKEN`	A job in the workspace already has that name, an archived one included. Choose another name, or restore and update the archived job
409	`CONFLICT`	Update: the job changed since you read it. `currentRevision` is the revision now

Each write records job.created or job.updated in the workspace’s change feed, internal only, and each agent write counts as one action.

Operator mirror

POST /v0/operator/jobs, GET /v0/operator/jobs, GET /v0/operator/jobs/{id} and PATCH /v0/operator/jobs/{id} take the same inputs without why, with an operator session acting as the bound account; the list takes the workspace by its id.

Overview

Identity

Notifications

Operators

Workspaces

Artifacts

Trash

Storage

Actions

Table Rows

Versions

Tasks

Activity

Search

Health

The job

`POST /v0/jobs`

`PATCH /v0/jobs/{id}`

`GET /v0/jobs/{id}`

`GET /v0/jobs`

A task’s job

Errors

Operator mirror

​The job

​POST /v0/jobs

​PATCH /v0/jobs/{id}

​GET /v0/jobs/{id}

​GET /v0/jobs

​A task’s job

​Errors

​Operator mirror

The job

`POST /v0/jobs`

`PATCH /v0/jobs/{id}`

`GET /v0/jobs/{id}`

`GET /v0/jobs`

A task’s job

Errors

Operator mirror