LuckPanda Documents API

openapi: 3.2.0
info:
  title: Luckpanda App Documents API
  version: 1.0.0
  description: 'Operations tagged Documents 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: Documents
paths:
  /documents:
    get:
      tags:
      - Documents
      operationId: listDocuments
      x-mcp-tool: document_list
      parameters:
      - $ref: '#/components/parameters/DocumentKind'
      - name: lifecycle
        in: query
        schema:
          type: string
          enum:
          - draft
          - issued
          - cancelled
      - name: party_id
        in: query
        schema:
          $ref: '#/components/schemas/Uuid'
      - name: external_ref
        in: query
        schema:
          type: string
          maxLength: 200
        description: Only the document with this external_ref.
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          $ref: '#/components/responses/Page'
      summary: List documents
      x-summary-source: derived
    post:
      tags:
      - Documents
      operationId: createDocumentDraft
      x-mcp-tool: document_draft_create
      summary: Create a draft (any kind)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentDraft'
      responses:
        '201':
          $ref: '#/components/responses/DocumentResult'
        '403':
          $ref: '#/components/responses/Problem'
        '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`
  /documents/{documentId}:
    get:
      tags:
      - Documents
      operationId: getDocument
      x-mcp-tool: document_get
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          description: The document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '404':
          $ref: '#/components/responses/Problem'
      summary: Get document
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/revisions:
    post:
      tags:
      - Documents
      operationId: reviseDocument
      x-mcp-tool: document_revise
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/DocumentResult'
        '409':
          $ref: '#/components/responses/Problem'
      summary: Revise document
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/attachments:
    get:
      tags:
      - Documents
      operationId: listDocumentAttachments
      summary: D92.
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          $ref: '#/components/responses/Page'
        '404':
          $ref: '#/components/responses/Problem'
    post:
      tags:
      - Documents
      operationId: attachDocumentFile
      summary: D92.
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              properties:
                file:
                  type: string
                  format: binary
                expected_version:
                  type: integer
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '409':
          $ref: '#/components/responses/Problem'
        '413':
          $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`
  /documents/{documentId}/attachments/{attachmentId}:
    get:
      tags:
      - Documents
      operationId: downloadDocumentAttachment
      summary: D92. The file itself (Content-Disposition attachment)
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      - name: attachmentId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      responses:
        '200':
          description: The file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/Problem'
    delete:
      tags:
      - Documents
      operationId: removeDocumentAttachment
      summary: D92.
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      - name: attachmentId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/Uuid'
      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`
  /documents/{documentId}/issue:
    post:
      tags:
      - Documents
      operationId: issueDocument
      x-mcp-tool: document_progress
      x-human-only-effect: true
      summary: Number and post the document
      description: Agent keys get `APPROVAL_REQUIRED` (403), or a proposal with `proposal_only`. Server-integration keys need `document.issue:sales` and must be within their limits.
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VersionedCommand'
      responses:
        '200':
          $ref: '#/components/responses/DocumentResult'
        '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`
  /documents/{documentId}/conversions:
    post:
      tags:
      - Documents
      operationId: convertDocument
      x-mcp-tool: document_progress
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/DocumentResult'
        '409':
          $ref: '#/components/responses/Problem'
      summary: Convert document
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/duplicate:
    post:
      tags:
      - Documents
      operationId: duplicateDocument
      x-mcp-tool: document_duplicate
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ToolInput'
      responses:
        '201':
          $ref: '#/components/responses/DocumentResult'
      summary: Duplicate document
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/send:
    post:
      tags:
      - Documents
      operationId: sendDocument
      x-mcp-tool: document_send
      x-human-only-effect: true
      summary: Email the document to the client, or make its link
      description: Without a mail provider configured the delivery is `link_only`. Server-integration keys need `document.send:sales`.
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CommandBase'
              - type: object
                properties:
                  expected_version:
                    type: integer
                    minimum: 1
                  channel:
                    type: string
                    enum:
                    - email
                    - link
                  to:
                    type: string
                    maxLength: 320
                  subject:
                    type: string
                    maxLength: 300
                  message:
                    type: string
                    maxLength: 4000
      responses:
        '200':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/cancel:
    post:
      tags:
      - Documents
      operationId: cancelDocument
      x-mcp-tool: document_cancel
      description: People only for issued documents; no key may cancel (it is not an integration effect).
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/VersionedCommand'
              - type: object
                properties:
                  reason:
                    type: string
                    maxLength: 1000
      responses:
        '200':
          $ref: '#/components/responses/DocumentResult'
        '403':
          $ref: '#/components/responses/Problem'
      summary: Cancel document
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/payment-link:
    post:
      tags:
      - Documents
      operationId: createPaymentLink
      x-mcp-tool: payment_link_create
      x-human-only-effect: true
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CommandBase'
              - type: object
                properties:
                  provider:
                    type: string
                    enum:
                    - manual
                    - stripe
                  instructions:
                    type: string
                    maxLength: 2000
                  expires_in_days:
                    type: integer
                    minimum: 1
                    maximum: 365
      responses:
        '201':
          $ref: '#/components/responses/CommandAccepted'
        '403':
          $ref: '#/components/responses/Problem'
      summary: Create payment link
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/lineage:
    get:
      tags:
      - Documents
      operationId: getDocumentLineage
      x-mcp-tool: document_lineage_get
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      responses:
        '200':
          $ref: '#/components/responses/Resource'
      summary: Get document lineage
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/pdf:
    get:
      tags:
      - Documents
      operationId: getDocumentPdf
      x-mcp-tool: document_pdf_get
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      - name: variant
        in: query
        schema:
          type: string
          enum:
          - auto
          - branded
          - clean
      responses:
        '200':
          description: The PDF
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        '402':
          $ref: '#/components/responses/Problem'
      summary: Get document pdf
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
  /documents/{documentId}/fulfillment-allocations:
    post:
      tags:
      - Documents
      operationId: allocateFulfillment
      x-status: planned
      description: 'Not served yet. Fulfilment goes through `document_progress` with `action: fulfill` over MCP.'
      parameters:
      - $ref: '#/components/parameters/DocumentId'
      responses:
        '501':
          $ref: '#/components/responses/Problem'
      summary: Allocate fulfillment
      x-summary-source: derived
    servers:
    - url: https://luckpanda.app/api/v1
    - url: http://127.0.0.1:8787/api/v1
      description: Local `wrangler dev`
components:
  parameters:
    DocumentKind:
      name: kind
      in: query
      schema:
        $ref: '#/components/schemas/DocumentKind'
    Limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 25
    DocumentId:
      name: documentId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/Uuid'
    Cursor:
      name: cursor
      in: query
      schema:
        type: string
        maxLength: 500
  responses:
    Resource:
      description: Authorized resource
      content:
        application/json:
          schema:
            type: object
            additionalProperties: true
    Page:
      description: Cursor page
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Page'
    Problem:
      description: Typed RFC 7807 error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    DocumentResult:
      description: The document after the command, with the command result under `operation`. A proposal or a dry run returns the bare command result.
      content:
        application/json:
          schema:
            oneOf:
            - $ref: '#/components/schemas/Document'
            - $ref: '#/components/schemas/CommandResult'
    CommandAccepted:
      description: 'Command result: succeeded, awaiting_approval (a proposal) or preview (dry_run)'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommandResult'
  schemas:
    Document:
      type: object
      description: The document view (abridged).
      required:
      - id
      - kind
      - lifecycle
      - version
      properties:
        id:
          $ref: '#/components/schemas/Uuid'
        kind:
          type: string
        lifecycle:
          type: string
          enum:
          - draft
          - issued
          - cancelled
        settlement:
          type: string
          enum:
          - unpaid
          - part_paid
          - paid
          - overpaid
          - not_applicable
        version:
          type: integer
        currency:
          $ref: '#/components/schemas/Currency'
        payable_minor:
          type: integer
        paid_minor:
          type: integer
        external_ref:
          type:
          - string
          - 'null'
        doc:
          type: object
          description: 'The editor document: number, dates, parties, lines, totals'
          additionalProperties: true
        operation:
          $ref: '#/components/schemas/CommandResult'
      additionalProperties: true
    DraftFields:
      type: object
      description: The document fields of `document_draft_create` (abridged; the tool schema also has India GST, export and display fields).
      properties:
        legal_entity_id:
          $ref: '#/components/schemas/Uuid'
          description: 'Default: the business''s first legal entity.'
        party_id:
          $ref: '#/components/schemas/Uuid'
        currency:
          $ref: '#/components/schemas/Currency'
        lines:
          type: array
          minItems: 1
          maxItems: 500
          items:
            $ref: '#/components/schemas/LineInput'
        buyer:
          $ref: '#/components/schemas/PartyBlock'
        seller:
          $ref: '#/components/schemas/PartyBlock'
        issue_date:
          $ref: '#/components/schemas/Date'
        due_date:
          oneOf:
          - $ref: '#/components/schemas/Date'
          - type: 'null'
        notes:
          type: string
          maxLength: 4000
        terms:
          type: string
          maxLength: 4000
        fx_rate_to_base:
          type: string
          pattern: ^[0-9]+(\.[0-9]{1,8})?$
          description: Needed when the currency differs from the business's base currency.
        country_code:
          type: string
          pattern: ^[A-Z]{2}$
        locale:
          type: string
          maxLength: 35
        external_ref:
          type: string
          minLength: 1
          maxLength: 200
          description: Your id for this document; unique per business and kind (DUPLICATE_EXTERNAL_REF on POST /documents).
        prices_include_tax:
          type: boolean
          description: 'D92: line prices include tax.'
        discount:
          $ref: '#/components/schemas/DocDiscount'
        round_off:
          type: boolean
          description: 'D92: round the total to a whole currency unit (a Round off line).'
        reverse_charge:
          type: boolean
          description: 'D92: India domestic B2B; tax shown, payable by the recipient, not added to the total.'
        payment_terms:
          type:
          - string
          - 'null'
          enum:
          - due_on_receipt
          - net_7
          - net_15
          - net_30
          - net_45
          - net_60
          - custom
          - null
          description: 'D92: a named term sets due_date.'
        custom_fields:
          type: array
          maxItems: 8
          items:
            type: object
            required:
            - label
            properties:
              label:
                type: string
                minLength: 1
                maxLength: 40
              value:
                type: string
                maxLength: 200
            additionalProperties: false
        show_bank_details:
          type: boolean
          description: 'D92: print the business bank details (and the UPI QR on Indian INR documents).'
        show_signature:
          type: boolean
    Date:
      type: string
      pattern: ^\d{4}-\d{2}-\d{2}$
    PartyBlock:
      type: object
      description: A buyer or seller as written on the document. The buyer is matched to an existing client by external_ref, then tax id, then email, then name; otherwise a new client is created.
      required:
      - name
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 300
        email:
          type: string
          maxLength: 320
        address:
          type: string
          maxLength: 1000
        country_code:
          type: string
          pattern: ^[A-Z]{2}$
        tax_id:
          type: string
          maxLength: 100
          description: For an Indian party this is the GSTIN.
        state_code:
          type: string
          pattern: ^[0-9]{2}$
        external_ref:
          type: string
          maxLength: 200
          description: 'Buyer only: your id for this customer.'
        phone:
          type: string
          maxLength: 40
        shipping_address:
          type: string
          maxLength: 1000
      additionalProperties: false
    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'
    DocumentKind:
      type: string
      enum:
      - quote
      - proforma
      - sales_order
      - delivery
      - invoice
      - purchase_request
      - purchase_order
      - goods_receipt
      - purchase_bill
      - credit_note
      - debit_note
      - receipt
    VersionedCommand:
      allOf:
      - $ref: '#/components/schemas/CommandBase'
      - type: object
        required:
        - expected_version
        properties:
          expected_version:
            type: integer
            minimum: 1
    Uuid:
      type: string
      format: uuid
    Quantity:
      type: string
      pattern: ^[0-9]+(\.[0-9]{1,6})?$
    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'
    Page:
      type: object
      required:
      - data
      properties:
        data:
          type: array
          maxItems: 100
          items:
            type: object
            additionalProperties: true
        next_cursor:
          type:
          - string
          - 'null'
    LineInput:
      type: object
      required:
      - description
      - quantity
      - unit_code
      - unit_price_minor
      properties:
        description:
          type: string
          minLength: 1
          maxLength: 4000
        item_id:
          $ref: '#/components/schemas/Uuid'
        quantity:
          $ref: '#/components/schemas/Quantity'
        unit_code:
          type: string
          maxLength: 32
        unit_price_minor:
          type: integer
          minimum: 0
        tax_rate_bp:
          type: integer
          minimum: 0
          maximum: 100000
          description: Tax rate in basis points (1800 = 18%).
        discount_minor:
          type: integer
          minimum: 0
        hsn_sac:
          type: string
          pattern: ^([0-9]{4}|[0-9]{6}|[0-9]{8})$
        cess_rate_bp:
          type: integer
          minimum: 0
          maximum: 50000
          description: 'India only (D92): GST cess rate on the line.'
      additionalProperties: false
    IdempotencyKey:
      type: string
      minLength: 16
      maxLength: 128
      pattern: ^[A-Za-z0-9._:-]+$
    Currency:
      type: string
      pattern: ^[A-Z]{3}$
    DocDiscount:
      description: D92 document discount before tax, shared across lines in proportion to their value. null removes it.
      type:
      - object
      - 'null'
      required:
      - type
      properties:
        type:
          enum:
          - percent
          - amount
        value_bp:
          type: integer
          minimum: 0
          maximum: 10000
        value_minor:
          type: integer
          minimum: 0
      additionalProperties: false
    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
    CommandBase:
      type: object
      required:
      - idempotency_key
      - correlation_id
      properties:
        idempotency_key:
          $ref: '#/components/schemas/IdempotencyKey'
        correlation_id:
          $ref: '#/components/schemas/Uuid'
        dry_run:
          type: boolean
          default: false
        proposal_only:
          type: boolean
          default: false
          description: Make it a proposal for a person to accept instead of acting.
        approval_request_id:
          $ref: '#/components/schemas/Uuid'
    CreateDocumentDraft:
      allOf:
      - $ref: '#/components/schemas/CommandBase'
      - $ref: '#/components/schemas/DraftFields'
      - type: object
        required:
        - kind
        - currency
        - lines
        properties:
          kind:
            $ref: '#/components/schemas/DocumentKind'
  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