Agents API

{"openapi":"3.1.0","info":{"title":"JOBFLOW APS","version":"1.0","description":"The JOBFLOW procurement automaton for existing trade flows. An invoice without a sealed proof pack is forbidden: invoice.issue before PROOF_PACK answers 409 GATE_PROOF_REQUIRED. Prices come only from the business. Platform fee cap CHF 5.00 per mandate and day."},"servers":[{"url":"https://agents.kulalabs.ch"}],"paths":{"/.well-known/jobflow.json":{"get":{"operationId":"canon","summary":"The APS 1.0 canon","responses":{"200":{"description":"The canon."}}}},"/verify/{chain_id}":{"get":{"operationId":"verify_get","summary":"Verify a chain","parameters":[{"name":"chain_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Chain and check result."},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intent.match":{"post":{"operationId":"intent_match","summary":"Check whether the flow exists","description":"The first call: says whether the user's request is a flow JOBFLOW already runs. A match answers do_not_build true, the capabilities it touches and the next call; no match answers 404 OUT_OF_SCOPE. Never: Guess: it names the words it matched. Free.","x-jobflow-effect":"read","x-jobflow-platform-fee-chf":0,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","minLength":1,"maxLength":5000,"description":"What the user asked for, in the user's words."}},"required":["text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/discover":{"post":{"operationId":"discover","summary":"Discover JOBFLOW","description":"Catalog, schemas, fees, gate, error codes; with a trade, the field knowledge for it. Never: —. Free.","x-jobflow-effect":"read","x-jobflow-platform-fee-chf":0,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"trade":{"description":"Trade id or name for field knowledge.","type":"string","maxLength":60}},"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/quote":{"post":{"operationId":"quote","summary":"Quote a platform fee","description":"The hard platform fee for a capability before it is called, with what is left of the daily cap. Never: Estimate the value of a job. Free.","x-jobflow-effect":"read","x-jobflow-platform-fee-chf":0,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"capability":{"type":"string","maxLength":40,"description":"The capability to price, as in discover, e.g. \"job.create\" or \"invoice.issue\"."},"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."}},"required":["capability"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/compare":{"post":{"operationId":"compare","summary":"Compare with building it","description":"Build-vs-buy next to the hard fee, the estimate marked NOT_A_QUOTE. Never: Present a token count or an estimate as a fact. Free.","x-jobflow-effect":"read","x-jobflow-platform-fee-chf":0,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"capabilities":{"description":"Capabilities to compare, as in discover, e.g. [\"intake.classify\", \"invoice.issue\"]. Leave out for all.","maxItems":20,"type":"array","items":{"type":"string","maxLength":40}},"needs":{"description":"Features the user needs beyond the basic flow; the answer recommends the smallest package that covers them.","maxItems":20,"type":"array","items":{"type":"string","enum":["kreislauf","einblick","tresor_lang","nachklang","team_5","handschlag","weiterwerk","wartung","bruecke","zahlungsruf","anzahlung_auto","team_all","autopilot","velocity","reserve","gebaeude","forderungspaket","rueckruf"]}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/mandate.create":{"post":{"operationId":"mandate_create","summary":"Create a mandate","description":"Creates a mandate and the out-of-band approval link for the owner. Never: Activate production. Free.","x-jobflow-effect":"propose","x-jobflow-platform-fee-chf":0,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"delegate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"vendor":{"type":"string","maxLength":60}},"required":["name"],"additionalProperties":false,"description":"You, the agent: your name and optionally who built you, e.g. {\"name\": \"Dispatch helper\", \"vendor\": \"Anthropic\"}."},"business":{"description":"The business the owner runs, as far as you know it, e.g. {\"name\": \"Muster Sanitär\", \"trade\": \"plumbing\", \"contact\": \"owner@example.ch\"}.","type":"object","properties":{"name":{"type":"string","maxLength":120},"trade":{"type":"string","maxLength":60},"contact":{"type":"string","maxLength":200}},"additionalProperties":false},"scopes":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"string","enum":["flow.propose","intake.classify","job.create","assign","schedule","proof.seal","invoice.issue","payment.collect"]},"description":"What the owner allows you to do, at least one, e.g. [\"intake.classify\", \"job.create\"]."},"channel":{"description":"Where the owner gets the approval link, e.g. {\"type\": \"whatsapp\", \"number_e164\": \"+41791234567\"}. Leave out to get the link back.","type":"object","properties":{"type":{"type":"string","const":"whatsapp"},"number_e164":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$"}},"required":["type","number_e164"],"additionalProperties":false},"expires_in_days":{"description":"Days until the mandate ends, 1 to 30.","type":"integer","minimum":1,"maximum":30},"paid_by":{"description":"Who pays the platform fees. business (default): billed to the business. agent: from your own credit; send your jfa_ key.","type":"string","enum":["business","agent"]},"sandbox":{"description":"true: a test mandate with sample data, approved at once, no fees, valid one day. The whole flow runs, payment is simulated, nothing reaches a real business.","type":"boolean"}},"required":["delegate","scopes"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/flow.configure":{"post":{"operationId":"flow_configure","summary":"Propose the flow","description":"The WhatsApp-to-payment flow for this mandate as a configuration proposal. Never: Bind a channel or an account without an approved mandate. Free.","x-jobflow-effect":"propose","x-jobflow-platform-fee-chf":0,"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."}},"required":["mandate_token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/intake.classify":{"post":{"operationId":"intake_classify","summary":"Classify a request","description":"Classifies a customer request and opens the flow (REQUEST → CLASSIFIED). Never: Set an emergency tariff. Platform fee CHF 0.05 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"mutate","x-jobflow-platform-fee-chf":0.05,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"text":{"type":"string","minLength":1,"maxLength":5000,"description":"The customer's message as written, e.g. \"Water under the sink, can someone come tomorrow?\"."},"channel_message_id":{"description":"The id of the message in its channel (WhatsApp, e-mail), so the same message is never taken twice.","type":"string","maxLength":200}},"required":["mandate_token","text"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/job.create":{"post":{"operationId":"job_create","summary":"Create the order","description":"Creates the order from the classification. Needs state CLASSIFIED. Never: Take a price from the request body. Platform fee CHF 0.05 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"mutate","x-jobflow-platform-fee-chf":0.05,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"flow_id":{"type":"string","pattern":"^f_[A-Za-z0-9_-]{8,100}$","description":"The flow (job) id, which is also its chain id."}},"required":["mandate_token","flow_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/assign":{"post":{"operationId":"assign","summary":"Assign a technician","description":"Assigns a technician by the business's rule. Needs state ORDER. Never: Treat free text as dispatching. Platform fee CHF 0.03 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"mutate","x-jobflow-platform-fee-chf":0.03,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"flow_id":{"type":"string","pattern":"^f_[A-Za-z0-9_-]{8,100}$","description":"The flow (job) id, which is also its chain id."}},"required":["mandate_token","flow_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/schedule":{"post":{"operationId":"schedule","summary":"Book the appointment","description":"Books the earliest free slot in the business's working windows. Needs state ASSIGNED. Never: Use the agent's calendar as the source. Platform fee CHF 0.03 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"mutate","x-jobflow-platform-fee-chf":0.03,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"flow_id":{"type":"string","pattern":"^f_[A-Za-z0-9_-]{8,100}$","description":"The flow (job) id, which is also its chain id."},"not_before":{"description":"Earliest start, ISO 8601 with offset, e.g. \"2026-11-03T08:00:00+01:00\".","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["mandate_token","flow_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/proof.seal":{"post":{"operationId":"proof_seal","summary":"Seal the proof pack","description":"Hashes and closes the proof pack after the work is completed. Needs state WORK_COMPLETED. Never: Issue the invoice. Platform fee CHF 0.05 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"mutate","x-jobflow-platform-fee-chf":0.05,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"flow_id":{"type":"string","pattern":"^f_[A-Za-z0-9_-]{8,100}$","description":"The flow (job) id, which is also its chain id."},"evidence":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["photo_before","photo_after","measurement","material_list","signature","note"]},"sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"label":{"type":"string","maxLength":200}},"required":["kind","sha256"],"additionalProperties":false},"description":"What proves the work, 1 to 200 items: kind, the SHA-256 of the file (64 hex characters) and a label, e.g. [{\"kind\": \"photo_after\", \"sha256\": \"<64 hex>\", \"label\": \"new siphon\"}]."}},"required":["mandate_token","flow_id","evidence"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invoice.issue":{"post":{"operationId":"invoice_issue","summary":"Issue the invoice","description":"Issues the invoice from the business's tariff and the reported work, only after the proof pack. Needs state PROOF_PACK. Never: Invent a price or skip the gate. Platform fee CHF 0.18 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"money","x-jobflow-platform-fee-chf":0.18,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"flow_id":{"type":"string","pattern":"^f_[A-Za-z0-9_-]{8,100}$","description":"The flow (job) id, which is also its chain id."}},"required":["mandate_token","flow_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment.collect":{"post":{"operationId":"payment_collect","summary":"Request payment","description":"Creates the payment request for the invoice (QR bill, TWINT, card). The flow reaches PAYMENT only on the signed event of the payment provider. Needs state INVOICE. Never: Mark anything paid or pay out without a settled status. Platform fee CHF 0.10 per accepted call: quote first, then send quote_id, mandate_token and idempotency_key.","x-jobflow-effect":"money","x-jobflow-platform-fee-chf":0.1,"parameters":[{"name":"X-Jobflow-Mandate","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of mandate_token in the body."},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of idempotency_key in the body."},{"name":"X-Jobflow-Quote","in":"header","required":false,"schema":{"type":"string"},"description":"Instead of quote_id in the body."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mandate_token":{"type":"string","pattern":"^jfm_[A-Za-z0-9_-]{20,100}$","description":"The mandate token from mandate.create."},"quote_id":{"type":"string","pattern":"^q_[A-Za-z0-9_-]{8,100}$","description":"A valid quote for this capability (quote)."},"idempotency_key":{"type":"string","pattern":"^[\\x21-\\x7e]{1,100}$","description":"Required on every mutate and money call; a retry with the same key returns the same result and is not charged again."},"flow_id":{"type":"string","pattern":"^f_[A-Za-z0-9_-]{8,100}$","description":"The flow (job) id, which is also its chain id."},"method":{"description":"How the customer pays: qr_bill (Swiss QR bill), twint or card.","type":"string","enum":["qr_bill","twint","card"]}},"required":["mandate_token","flow_id"],"additionalProperties":false}}}},"responses":{"200":{"description":"Accepted."},"400":{"description":"An APS error: { error, message, ... }. See /.well-known/jobflow.json errors.","content":{

# --- truncated at 32 KB (34 KB total) ---
# Full source: https://artifacts.apis.io/kulalabs-ch/openapi/_original/agents-openapi.json