LuckPanda Payroll API

openapi: 3.2.0
info:
  title: Luckpanda App Payroll API
  version: 1.0.0
  description: 'Operations tagged Payroll across 2 of this provider''s published API definitions: openapi.yaml, luckpanda-app-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://luckpanda.app/api/v1
- url: http://127.0.0.1:8787/api/v1
  description: Local `wrangler dev`
security:
- bearerAuth: []
tags:
- name: Payroll
  description: UK, US federal and Canada (outside Québec) payroll; journal import elsewhere. Never holds or moves money (D109).
paths:
  /payroll/settings:
    get:
      tags:
      - Payroll
      operationId: getPayrollSettings
      x-mcp-tool: payroll_settings_get
      summary: Payroll setup of a legal entity with its setup issues and rule version
      responses:
        '200':
          $ref: '#/components/responses/Page'
    put:
      tags:
      - Payroll
      operationId: setPayrollSettings
      x-mcp-tool: payroll_settings_set
      summary: Human-only (payroll.settings).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/billing:
    get:
      tags:
      - Payroll
      operationId: getPayrollBilling
      x-mcp-tool: payroll_billing_get
      summary: Active employees this billing period, the 5 the module covers, extra employees…
      responses:
        '200':
          description: The Payroll meter
          content:
            application/json:
              schema:
                type: object
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/rules:
    get:
      tags:
      - Payroll
      operationId: listPayrollRules
      x-mcp-tool: payroll_rules_list
      summary: Rule versions with sources, verification status and test-vector results
      responses:
        '200':
          $ref: '#/components/responses/Page'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/employees:
    get:
      tags:
      - Payroll
      operationId: listPayrollEmployees
      x-mcp-tool: payroll_employee_list
      summary: Employees (identifiers and bank details masked)
      responses:
        '200':
          $ref: '#/components/responses/Page'
    post:
      tags:
      - Payroll
      operationId: createPayrollEmployee
      x-mcp-tool: payroll_employee_manage
      summary: Create an employee (action create). Bank details and identifiers are human-only
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/employees/{employeeId}:
    parameters:
    - name: employeeId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    get:
      tags:
      - Payroll
      operationId: getPayrollEmployee
      x-mcp-tool: payroll_employee_get
      summary: One employee with items, payslips and year to date; reveal=true…
      responses:
        '200':
          $ref: '#/components/responses/Page'
    post:
      tags:
      - Payroll
      operationId: managePayrollEmployee
      x-mcp-tool: payroll_employee_manage
      summary: update, terminate, rehire, set_item, end_item
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs:
    get:
      tags:
      - Payroll
      operationId: listPayRuns
      x-mcp-tool: pay_run_list
      summary: Pay runs, newest first
      responses:
        '200':
          $ref: '#/components/responses/Page'
    post:
      tags:
      - Payroll
      operationId: createPayRun
      x-mcp-tool: pay_run_create
      summary: Create a draft run and compute every payslip (agents may draft)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '409':
          $ref: '#/components/responses/Problem'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/preview:
    post:
      tags:
      - Payroll
      operationId: previewPayRun
      x-mcp-tool: pay_run_preview
      summary: 'Compute without saving, or preview a draft run: payslips, review seals, journal…'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/Page'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/{runId}:
    parameters:
    - name: runId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    get:
      tags:
      - Payroll
      operationId: getPayRun
      x-mcp-tool: pay_run_list
      summary: One run with payslips, review diff, liabilities and bank files
      responses:
        '200':
          $ref: '#/components/responses/Page'
    patch:
      tags:
      - Payroll
      operationId: updatePayRun
      x-mcp-tool: pay_run_update
      summary: Change inputs of a draft (hours, one-off items) and recompute, or discard it
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/{runId}/preview:
    parameters:
    - name: runId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    get:
      tags:
      - Payroll
      operationId: previewSavedPayRun
      x-mcp-tool: pay_run_preview
      summary: Preview a saved run
      responses:
        '200':
          $ref: '#/components/responses/Page'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/{runId}/approve:
    parameters:
    - name: runId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    post:
      tags:
      - Payroll
      operationId: approvePayRun
      x-mcp-tool: pay_run_approve
      summary: Human-only (payroll.approve).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/{runId}/post:
    parameters:
    - name: runId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    post:
      tags:
      - Payroll
      operationId: postPayRun
      x-mcp-tool: pay_run_post
      summary: Human-only (payroll.post).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '402':
          $ref: '#/components/responses/Problem'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/{runId}/reverse:
    parameters:
    - name: runId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    post:
      tags:
      - Payroll
      operationId: reversePayRun
      x-mcp-tool: pay_run_reverse
      summary: Human-only (payroll.post), reason required.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/runs/{runId}/payslips/{employeeId}/pdf:
    parameters:
    - name: runId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    - name: employeeId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    get:
      tags:
      - Payroll
      operationId: getPayslipPdf
      summary: The payslip as a PDF (NOT POSTED watermark before posting)
      responses:
        '200':
          description: PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/liabilities:
    get:
      tags:
      - Payroll
      operationId: listPayrollLiabilities
      x-mcp-tool: payroll_liability_list
      summary: What is owed to each authority, grouped by due date, with due seals, the…
      responses:
        '200':
          $ref: '#/components/responses/Page'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/liabilities/settle:
    post:
      tags:
      - Payroll
      operationId: settlePayrollLiabilities
      x-mcp-tool: payroll_liability_settle
      summary: Human-only (payroll.pay).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/filings:
    get:
      tags:
      - Payroll
      operationId: listPayrollFilings
      x-mcp-tool: payroll_filing_list
      summary: Generated filings with validation results
      responses:
        '200':
          $ref: '#/components/responses/Page'
    post:
      tags:
      - Payroll
      operationId: generatePayrollFiling
      x-mcp-tool: payroll_filing_generate
      summary: Build FPS, EPS, P60, P45, 941, 940, W-2, EFW2, T4, ROE or PD7A from posted…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/filings/{filingId}:
    parameters:
    - name: filingId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    get:
      tags:
      - Payroll
      operationId: getPayrollFiling
      x-mcp-tool: payroll_filing_list
      summary: One filing
      responses:
        '200':
          $ref: '#/components/responses/Page'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/filings/{filingId}/submit:
    parameters:
    - name: filingId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    post:
      tags:
      - Payroll
      operationId: submitPayrollFiling
      x-mcp-tool: payroll_filing_submit
      summary: Human-only (payroll.file).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/filings/{filingId}/download:
    parameters:
    - name: filingId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    - name: as
      in: query
      schema:
        enum:
        - pdf
    get:
      tags:
      - Payroll
      operationId: downloadPayrollFiling
      summary: The file (XML, EFW2 text, JSON worksheet); as=pdf gives W-2 or P60 employee…
      responses:
        '200':
          description: File
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/bank-files:
    get:
      tags:
      - Payroll
      operationId: listPayrollBankFiles
      x-mcp-tool: payroll_bank_file_list
      summary: Generated net-pay files
      responses:
        '200':
          $ref: '#/components/responses/Page'
    post:
      tags:
      - Payroll
      operationId: generatePayrollBankFile
      x-mcp-tool: payroll_bank_file_generate
      summary: NACHA PPD, Bacs Standard 18, UK CSV, CPA-005, ABA or SEPA pain.001 for a posted…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/bank-files/{bankFileId}/release:
    parameters:
    - name: bankFileId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    post:
      tags:
      - Payroll
      operationId: releasePayrollBankFile
      x-mcp-tool: payroll_bank_file_release
      summary: Human-only (payroll.bank_release).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
        '409':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /payroll/journal-import:
    post:
      tags:
      - Payroll
      operationId: importPayrollJournal
      x-mcp-tool: payroll_journal_import
      summary: Post payroll journals from another payroll system (CSV, mapped columns); agents…
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '422':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
components:
  responses:
    Problem:
      description: Typed RFC 7807 error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Page:
      description: Cursor page
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Page'
    CommandAccepted:
      description: 'Command result: succeeded, awaiting_approval (a proposal) or preview (dry_run)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommandResult'
  schemas:
    Problem:
      type: object
      required:
      - type
      - title
      - status
      - code
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        code:
          type: string
          description: 'VALIDATION_FAILED (422) the body or a field is wrong; see field_errors.

            FORBIDDEN (401 no or revoked key, 403 missing permission or grant).

            NOT_FOUND (404).

            APPROVAL_REQUIRED (403) an agent (or any key over /mcp) tried to issue, send or pay; send proposal_only to propose instead.

            INTEGRATION_LIMIT (403) a server-integration key is outside its kinds, legal entities or largest total.

            PAYWALL (402) the business has not unlocked the outcome (issuing needs the Sales module); the body names the module.

            INVALID_STATE (409) the document is not in a state that allows this (e.g. issuing a cancelled document).

            STALE_VERSION (409) expected_version is behind; reload and retry.

            IDEMPOTENCY_MISMATCH (409) the idempotency_key was used with a different body.

            DUPLICATE_EXTERNAL_REF (409) a document of this kind already has this external_ref.

            COMPLIANCE_BLOCKED (409) a compliance rule blocks the change (e.g. cancelling a document with an active e-invoice IRN).

            ALLOCATION_EXCEEDS_AVAILABLE (409) a payment allocation is more than the receipt or the amount due allows.

            NOT_IMPLEMENTED (501) a path or option that is planned but not served.

            DELIVERY_FAILED (502, /invoices send step) the email provider refused the message.

            RATE_LIMITED (429).

            '
          enum:
          - VALIDATION_FAILED
          - FORBIDDEN
          - NOT_FOUND
          - APPROVAL_REQUIRED
          - INTEGRATION_LIMIT
          - PAYWALL
          - INVALID_STATE
          - STALE_VERSION
          - IDEMPOTENCY_MISMATCH
          - DUPLICATE_EXTERNAL_REF
          - COMPLIANCE_BLOCKED
          - ALLOCATION_EXCEEDS_AVAILABLE
          - CONFLICT
          - NOT_IMPLEMENTED
          - DELIVERY_FAILED
          - RATE_LIMITED
          - INTERNAL_ERROR
        message:
          type: string
        field_errors:
          type: array
          items:
            type: object
            required:
            - path
            - code
            properties:
              path:
                type: string
              code:
                type: string
        correlation_id:
          $ref: '#/components/schemas/Uuid'
    CommandResult:
      type: object
      required:
      - operation_id
      - status
      - correlation_id
      properties:
        operation_id:
          $ref: '#/components/schemas/Uuid'
        status:
          type: string
          enum:
          - succeeded
          - awaiting_approval
          - preview
        correlation_id:
          $ref: '#/components/schemas/Uuid'
        resource:
          type: object
          additionalProperties: true
        approval_request_id:
          $ref: '#/components/schemas/Uuid'
    Page:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          maxItems: 100
          items:
            type: object
            additionalProperties: true
        next_cursor:
          type:
          - string
          - 'null'
    ToolInput:
      type: object
      description: The input schema of the operation's `x-mcp-tool` (minus the ids the path supplies). See `architecture/mcp-tools.json`.
      required:
      - idempotency_key
      - correlation_id
      additionalProperties: true
    Uuid:
      type: string
      format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque API key, lpk_...
      description: Made in Workspace > Developers (agent or server-integration). Not a JWT.
x-refined-from:
- openapi.yaml
- luckpanda-app-openapi.yaml