Skip to main content

​
What a job is

A job is standing work in a workspace: 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 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, right after your instructions:
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, update or report 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) 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 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

​
Surfaces

Jobs API

Routes, bodies and refusals

Tasks

The work a job’s agents do, one task at a time