job-card

Open a job card for a job your crew is taking on and return its JC-YYYY-NNNN number: the client, the site, what the job is, the currency and when it is scheduled. Free tier: 10 active cards; archiving a finished job frees its slot.

{
  "type": "object",
  "properties": {
    "client": {
      "type": "string",
      "maxLength": 200,
      "description": "Who the job is for, e.g. Kowalski bathroom refit, or Acme Ltd"
    },
    "site": {
      "type": "string",
      "maxLength": 400,
      "description": "Where the job is, e.g. 14 Nowa Street, flat 3"
    },
    "description": {
      "type": "string",
      "maxLength": 2000,
      "description": "What the job is, e.g. Replace the consumer unit and certify"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO code the rates and prices are in"
    },
    "scheduled_date": {
      "type": "string",
      "maxLength": 10,
      "description": "The date the crew is due on site, YYYY-MM-DD. May be in the future; it is a plan, not a log"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "client",
    "site",
    "description",
    "currency"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Log hours worked on a job card: who did the work, the day, the hours and the hourly rate in whole cents, with a note on what was done. The line value is hours times rate, rounded half-up to the cent, fixed the moment it is logged.

{
  "type": "object",
  "properties": {
    "card": {
      "type": "string",
      "maxLength": 200,
      "description": "The job card id, e.g. JC-2026-0003, or the client name when only one card has it"
    },
    "worker": {
      "type": "string",
      "maxLength": 200,
      "description": "Who did the work, e.g. Anna"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the work was done, YYYY-MM-DD. A future date is refused"
    },
    "hours": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 24,
      "description": "Hours worked, to the hundredth, e.g. 7.5 or 3.25. One entry is one worker's day at most"
    },
    "rate_cents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100000000000000,
      "description": "The hourly rate in whole cents. 4500 is 45.00 an hour"
    },
    "note": {
      "type": "string",
      "maxLength": 2000,
      "description": "What was done, e.g. First fix, kitchen ring main"
    }
  },
  "required": [
    "card",
    "worker",
    "date",
    "hours",
    "rate_cents"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Log materials used on a job card: the item, the day it went in, the quantity and the unit cost in whole cents. The line value is quantity times unit cost, rounded half-up to the cent, fixed the moment it is logged.

{
  "type": "object",
  "properties": {
    "card": {
      "type": "string",
      "maxLength": 200,
      "description": "The job card id, e.g. JC-2026-0003, or the client name when only one card has it"
    },
    "item": {
      "type": "string",
      "maxLength": 200,
      "description": "What went into the job, e.g. Copper pipe 15mm, or Consumer unit 10-way"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day it went in, YYYY-MM-DD. A future date is refused"
    },
    "qty": {
      "type": "number",
      "exclusiveMinimum": 0,
      "maximum": 1000000,
      "description": "How many, to the thousandth, e.g. 2 or 0.5"
    },
    "unit_cost_cents": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100000000000000,
      "description": "What one costs in whole cents. 1299 is 12.99"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "card",
    "item",
    "date",
    "qty",
    "unit_cost_cents"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Move one job card exactly one step: open, in_progress, done, invoiced, archived, stamping the date and an optional note into its history. A skipped or backwards step is refused and nothing is written. Archiving a finished job frees a free-tier slot.

{
  "type": "object",
  "properties": {
    "card": {
      "type": "string",
      "maxLength": 200,
      "description": "The job card id, e.g. JC-2026-0003, or the client name when only one card has it"
    },
    "status": {
      "type": "string",
      "maxLength": 20,
      "description": "The next step for this card: open, in_progress, done, invoiced, archived. in-progress is accepted too"
    },
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The date to stamp the step with, YYYY-MM-DD. Default today"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "card",
    "status"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

List job cards newest first: client, site, status, hours logged, and the labor, materials and grand totals in cents. Filter by status and by client. Totals are kept per currency, never mixed.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "maxLength": 20,
      "description": "Only cards at this status: open, in_progress, done, invoiced, archived"
    },
    "client": {
      "type": "string",
      "maxLength": 200,
      "description": "Only cards whose client contains this text, case-insensitive"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Read one job card in full by JC number or client: every labor entry and every material used, the hours per worker, and the running totals -- labor, materials and grand total -- as integer cents with formatted amounts. Reads only.

{
  "type": "object",
  "properties": {
    "card": {
      "type": "string",
      "maxLength": 200,
      "description": "The job card id, e.g. JC-2026-0003, or the client name when only one card has it"
    }
  },
  "required": [
    "card"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Render a job card ready to print and hand to the client: the labor, the materials, the totals and a signature line for client sign-off. Markdown, or self-contained HTML that needs nothing from the network. Writes nothing.

{
  "type": "object",
  "properties": {
    "card": {
      "type": "string",
      "maxLength": 200,
      "description": "The job card id, e.g. JC-2026-0003, or the client name when only one card has it"
    },
    "format": {
      "type": "string",
      "enum": [
        "markdown",
        "html"
      ],
      "description": "markdown (default) or html. The HTML carries its own styling and references nothing external"
    }
  },
  "required": [
    "card"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Delete a job card entered by mistake. One with labor or materials logged is refused, naming what it holds, because deleting it would lose the record of work done: archive it instead. The JC number is never reissued.

{
  "type": "object",
  "properties": {
    "card": {
      "type": "string",
      "maxLength": 200,
      "description": "The job card id, e.g. JC-2026-0003, or the client name when only one card has it"
    }
  },
  "required": [
    "card"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Hours and value for a day or a week: the job cards touched, the hours per worker, and the labor, materials and total value, kept per currency. A week runs Monday to Sunday. Touched means a labor or material entry dated inside the window.

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "A date inside the window, YYYY-MM-DD. Default today"
    },
    "span": {
      "type": "string",
      "enum": [
        "day",
        "week"
      ],
      "description": "day (default) is the date itself; week is the Monday to Sunday containing it"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}