---
name: jobbit
description: "How to work with Jobbit from another agent or program, through its MCP server or its REST API at platform.jobbit.uk. Load it when you are asked to use Jobbit: give the Jobbit agent a task, deploy or manage an app hosted on Jobbit, run an automation, upload or fetch files, call Jobbit's AI models, manage domains and projects, or check the account's credits and usage."
---

# Jobbit

Jobbit is an AI agent that does the work rather than describing it: it builds and hosts sites and apps, writes documents, makes images, video and audio, researches, runs automations and works in the services a person connects. People use it at https://jobbit.uk and in the mobile app. This file is for agents and programs that work with a person's Jobbit account from outside.

The newest version of this file is always at https://platform.jobbit.uk/skill.md. Full documentation: https://docs.jobbit.uk.

## Two ways in

| | Address | Best for |
|---|---|---|
| **MCP** | `https://platform.jobbit.uk/mcp` (streamable HTTP) | agents: Claude, Codex, Cursor, ChatGPT and any MCP client |
| **REST** | `https://platform.jobbit.uk/v1` | programs and scripts |

Both act for one person, with the same permissions, limits and spend. The machine-readable schema of the REST API is at `https://platform.jobbit.uk/v1/openapi.json` (agent task, automation and project routes pass through to Jobbit's agent and are listed in this file instead).

## Signing in

**An API key.** The person creates one in Jobbit: Settings → API keys (`https://jobbit.uk/app#settings/API`) → **New key**. They choose what it may do, an expiry and, if they want, limits (credits per day or month, which apps, models or workspaces). The key looks like `jb_live_…` and is shown once. Send it as `Authorization: Bearer jb_live_…`. Never print a key, write it into a file the person did not ask for, or put it in a URL.

**OAuth, for MCP clients that sign in themselves.** Point the client at `https://platform.jobbit.uk/mcp`. It finds the sign-in from the server's 401, registers itself and opens Jobbit's consent page, where the person sees the client and the permissions and may untick any. The client then gets an access token for an hour and a refresh token. The connection shows in the person's Jobbit under Settings → Integrations (and in their API keys as "<client> (OAuth)"), where they can disconnect it. A connection unused for 90 days lapses, and the person signs the client in again. Without requested scopes a client gets every permission except `deploy:admin` and `billing:write`.

### Connecting common clients

- **Claude (claude.ai, desktop):** Settings → Connectors → **Add custom connector**, name it Jobbit, URL `https://platform.jobbit.uk/mcp`, then **Connect** and approve on Jobbit's page.
- **Claude Code:** `claude mcp add --transport http jobbit https://platform.jobbit.uk/mcp`, then run `/mcp` and sign in. With a key instead: add `--header "Authorization: Bearer $JOBBIT_API_KEY"`.
- **Codex CLI:** `codex mcp add jobbit --url https://platform.jobbit.uk/mcp`, then `codex mcp login jobbit`. With a key instead, in `~/.codex/config.toml`:

  ```toml
  [mcp_servers.jobbit]
  url = "https://platform.jobbit.uk/mcp"
  bearer_token_env_var = "JOBBIT_API_KEY"
  ```

- **Codex in the IDE:** gear menu → **MCP servers** → **Add server** → **Streamable HTTP**, the URL above, save, restart the extension, then **Authenticate**.

## Permissions

A key or grant carries scopes. A write scope includes its read.

| Scope | Allows |
|---|---|
| `account:read` | the person, their plan, balance, credit history and usage |
| `billing:write` | payment links for plans and credit packs |
| `ai` | Jobbit's models: chat, embeddings, images, speech, transcription, music, video |
| `agent:read`, `agent:write` | read, start, answer and cancel agent tasks |
| `files:read`, `files:write` | uploads for tasks and the person's Library |
| `deploy:read`, `deploy:write`, `deploy:admin` | hosted apps, builds, logs, env, domains of apps; admin also deletes apps and reads database credentials |
| `automations:read`, `automations:run`, `automations:write` | automations, their runs, versions and data |
| `webhooks:write` | event subscriptions and webhook secrets |
| `projects:read`, `projects:write` | projects, their chats, files, notes and members |
| `domains:read`, `domains:write` | domains bought through Jobbit, their DNS and mail |

A request outside the key's scopes or limits is refused with 403 and says which permission is missing; ask the person to change the key rather than working around it.

## What there is

### Account and money

- `GET /v1/key`: this key, its owner, scopes, limits and expiry. Call it first to see what you may do.
- `GET /v1/me`, `GET /v1/plan`, `GET /v1/balance`, `GET /v1/transactions`, `GET /v1/usage`.
- `GET /v1/billing/products`, `POST /v1/billing/checkout {price_id}`: a Stripe link **for the person to open and pay**. You never pay.

Work costs credits from the person's balance: model calls, agent tasks, automation runs, video. Say what you are about to spend when it is more than small, and stop when the balance runs out (402 or `insufficient_credits`).

### The Jobbit agent

Give the agent a whole job and let it work; it has its own computer, browser, files and the person's plugins.

- `POST /v1/agent-tasks` with `goal` (what to do and when it counts as done) and, optionally, `input` (data, treated as data, not instructions), `output_schema` (JSON Schema the result must follow), `files` (ids from `POST /v1/files`, up to 20), `workspace` `{key, title}` (tasks with the same key share a chat, its files and history), `model`, `effort`, `limits` `{max_credits, max_minutes, max_turns}`, `idempotency_key`, `on_question` (`fail`, or `ask` to let the agent stop with a question). Returns at once with the task id.
- Follow it: `GET /v1/agent-tasks/{id}` until it finishes, or `GET /v1/agent-tasks/{id}/events` (server-sent events: `status` on every change, `finished` with the result; `Last-Event-ID` resumes). Statuses: `queued`, `running`, `waiting_input`, `succeeded`, `failed`, `cancelled`.
- The result has `output` (following your schema) or `text`, `artifacts` (files the agent made, as signed links) and a link to the chat where the person can watch the work.
- `waiting_input` carries a `question`: answer with `POST /v1/agent-tasks/{id}/input`. `POST /v1/agent-tasks/{id}/cancel` stops a task.

### Files and the Library

- `POST /v1/files` (multipart field `file`, up to 100 MB) → an id to hand to a task; `GET /v1/files`, `GET /v1/files/{id}`, `GET /v1/files/{id}/content`, `DELETE /v1/files/{id}`.
- `GET /v1/library?search=&type=&sort=`: the files the agent made across the person's chats, newest version first with signed links; `DELETE /v1/library/{id}`.

### AI models

OpenAI-compatible, so an OpenAI SDK works with `base_url = "https://platform.jobbit.uk/v1"` and the key as the API key.

- `GET /v1/models`, `POST /v1/chat/completions` (streaming included), `POST /v1/embeddings`.
- `POST /v1/images/generations`, `POST /v1/audio/speech`, `POST /v1/audio/transcriptions`, `POST /v1/audio/music`; catalogues under `/v1/images/models`, `/v1/audio/models`, `/v1/audio/voices`.
- Video is a job: `POST /v1/videos` (202), `GET /v1/videos/{id}` until `completed`, then `GET /v1/videos/{id}/content`.

### Hosted apps

Jobbit hosts the person's apps. A project needs a `Dockerfile` at its root that listens on port 8080 as a non-root user.

1. `POST /v1/uploads` with the project as a `.tar.gz` body → `upload_id`.
2. `POST /v1/apps {upload_id, name?, env?, database?: "managed"}` → 202 with a deployment. Hosting adds a suffix to the name while building; the final name and address come in the deployment.
3. `GET /v1/deployments/{id}` until it is `deployed` or failed; `GET /v1/deployments/{id}/logs` for the build log.

Then: `GET /v1/apps`, `GET /v1/apps/{name}`, `POST /v1/apps/{name}/deployments` (a new version, rolled back if it fails), `POST /v1/apps/{name}/restart`, `GET/PUT /v1/apps/{name}/env` (PUT merges), `GET /v1/apps/{name}/logs`, `/usage`, `/usage/history`, `/analytics[/{report}]`, `PUT|DELETE /v1/apps/{name}/domain` and `GET .../domain/check` (the person's own domain, paid plans), `DELETE /v1/apps/{name}` (keeps a managed database unless `drop_database=true`). Managed databases: `GET /v1/databases`, `GET /v1/databases/{id}`, credentials and password reset with `deploy:admin`.

### Automations

Work that runs on its own: on a schedule, by webhook, by email, when new items appear in a service, or on another automation's event. Under `/v1/automations` (the same as Jobbit's agent API): list and read automations, runs, versions and data; `POST /v1/automations/{id}/runs` starts a run; runs can be cancelled, retried and answered, approvals given. Creating and changing one is easier through an agent task: the agent builds it and asks the person to approve it in Jobbit.

### Projects

`/v1/projects/...`: a person's projects as in the app: create, list, change, members and invites, chats, knowledge, files, notes, exports. Project secrets never pass through the API.

### Domains

`GET /v1/domains`, `GET /v1/domains/check?domain=` (free or not, and the yearly price), `POST /v1/domains/checkout` and `POST /v1/domains/{id}/renew` (payment links for the person), `PUT|DELETE /v1/domains/{id}/app`, `PUT|DELETE /v1/domains/{id}/mail`, DNS records under `/v1/domains/{id}/dns-records`.

### Webhooks

`POST /v1/webhooks {url, events}` for `agent_task.finished`, `deployment.succeeded`, `deployment.failed`, `balance.low`, `automation_run.finished`. Deliveries are signed: `X-Jobbit-Signature: sha256=<hex>` is the HMAC-SHA256 of `<X-Jobbit-Timestamp>.<body>` with the webhook's secret. Failed deliveries are retried for a day; event ids are stable, so handle repeats.

## Limits and errors

- Errors are always `{"error": {"code", "message", "details"?, "request_id"}}`. Quote the `request_id` when something has to be reported to Jobbit support.
- Rate limits depend on the plan; every answer has `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`. On 429, wait for `Retry-After`. Chat, embeddings and decisions also share a tokens-per-minute budget (see `GET /v1/plan`).
- Request bodies are capped at 1 MB on most routes (25 MB on chat and audio, 20 MB for automation packages, 100 MB for files).
- Retrying a create with the same `idempotency_key` returns the same task instead of a second one.

## How to behave

- Check `GET /v1/key` before acting, and stay inside what the key allows.
- Ask the person before anything that spends many credits, deletes, replaces an app's live version or changes DNS.
- Payment links, consent and sign-ins to the person's services are for the person to complete in Jobbit; hand them the link.
- Prefer one agent task with a clear `goal` over many small calls when the job needs judgement or several tools.
- Point the person to https://jobbit.uk/app to watch a task's chat or an app, and to https://docs.jobbit.uk for how Jobbit works.