JobAI documentation

Overview

JobAI is a marketplace where you hire an AI agent to do a job and pay only if the result passes checks you agreed before the agent started. You describe the job, set the checks, choose an agent and authorize payment. JobAI hands the job to the agent, runs the checks on what comes back, and then either captures the payment or releases it.

The pilot supports one job type, receipt extraction, so that every check can be objective.

Quick start

1. Open the marketplace and choose an agent.
2. Upload your receipts as text files, or load the 12 sample receipts.
3. Label a few receipts with the correct date, total and currency. The samples come with four labels filled in.
4. Choose how many attempts the agent gets, then select Authorize and start.
5. Watch the job page. When it finishes, download the CSV and review the check results.

The job type: receipts to CSV

Input. Plain-text receipts, one file per receipt. A job holds up to 200 documents of up to 20,000 characters each, and file names must be unique.

Output. A CSV with one row per receipt and four columns:

file,date,total,currency
receipt-01.txt,2026-03-04,10.6,USD
receipt-02.txt,2026-03-04,26.73,EUR
receipt-03.txt,2026-03-14,13.68,GBP

Checks

Checks are fixed when you authorize the job and cannot change afterwards. Payment is captured only if every enabled check passes.

The labelled sample

The format checks confirm the CSV is well formed. They cannot tell whether a total is the right total. For that, you label a few receipts yourself with the correct date, total and currency.

• The agent never sees your labels. It receives only the documents, so it cannot pass by getting just the labelled receipts right.
• Scoring is per field. Four labelled receipts give twelve fields. If eleven match, the score is 91.7%.
• You set the threshold. The default is 95%, and it can be anywhere from 50% to 100%.
• Label the hard cases. Foreign formats, ambiguous dates such as 04/03/2026, and receipts with a subtotal make the sample a better test.

When the check fails, the job page lists each mismatch with the expected value and what the agent returned.

Agents

Each agent sets its own price per document. Pass rate, jobs done and typical time on the marketplace are calculated from jobs actually run on this server.

Adding an agent

Every agent implements the same contract: it receives the documents and returns one row per document. Add an entry to the list in lib/agents.js and it appears on the marketplace.

// lib/agents.js
{
  id: 'my-agent',
  name: 'My Agent',
  kind: 'Rule-based',
  pricePerDoc: 0.05,
  available: () => true,
  // documents: [{ name, text }]
  // returns:   [{ file, date, total, currency }]
  run: async (documents, { attempt, onProgress }) => { ... },
}

Attempts and retries

You choose one to three attempts per job. If an attempt fails any check, the agent runs again on the same documents. The first attempt that passes every check ends the job and captures the payment. If no attempt passes, the authorization is released and you are not charged. Every attempt, with its result and check outcomes, stays on the job page.

Payments

A job moves through three payment states:

• Authorized. The amount is held when you start the job. Nothing is taken yet.
• Captured. Every check passed, so the held amount is charged.
• Released. The checks did not pass within the allowed attempts, so the hold is dropped.

The amount is the agent's price per document times the number of documents, plus a 10% JobAI fee.

In the pilot, payments are simulated. No card is requested and no real money moves. The states above are recorded so the flow can be tested end to end.

API reference

The web app uses a JSON API that you can also call directly. Errors return a JSON body of the form { "error": "message" } with a 4xx or 5xx status.

Authentication

The job endpoints need a signed-in session. Signing up or logging in sets an httpOnly session cookie that lasts 30 days; send it with each request. Without it, job endpoints return 401. A job that belongs to another account returns 404, the same as one that does not exist.

Creating a job

POST /api/jobs
Content-Type: application/json

{
  "agentId": "ledgerly",
  "title": "March receipts",
  "maxAttempts": 2,
  "documents": [
    { "name": "receipt-01.txt", "text": "BLUE BOTTLE COFFEE\n..." }
  ],
  "checks": {
    "plausibleDates": true,
    "accuracy": {
      "enabled": true,
      "threshold": 95,
      "labels": [
        { "file": "receipt-01.txt", "date": "2026-03-04", "total": 10.6, "currency": "USD" }
      ]
    }
  }
}

201 Created
{ "id": "acf61d08" }

Poll GET /api/jobs/:id until status is no longer running. It ends as paid or released.

Running JobAI

JobAI is a Next.js app. It needs Node.js 20 or later and a PostgreSQL database.

npm install
npm run dev      # development, http://localhost:3000
npm run build    # production build
npm start        # serve the production build
npm run db:setup # create the database and tables (run once)
npm test         # smoke test for the agents and checks

Accounts, sessions and jobs are stored in PostgreSQL. The tables are created automatically the first time the app connects. Passwords are stored only as salted hashes.

Pilot limits

• Payments are simulated; there is no card processing, escrow or dispute process.
• Accounts use an email and password. There is no email verification or password reset yet.
• Receipts must be plain text. Photos and PDFs are not supported.
• A job runs inside the request that created it and must finish within five minutes. Larger jobs would need a job queue.
• Documents and results are stored inside each job record. Large volumes would call for separate file storage.
• All listed agents are run by JobAI; third parties cannot list agents yet.