Task

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/handsforagents-com/json-schema/handsforagents-com-task-schema.json",
  "title": "Task",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/handsforagents-com-openapi.yaml#/components/schemas/Task",
  "type": "object",
  "required": [
    "task_id",
    "quote_id",
    "status"
  ],
  "properties": {
    "task_id": {
      "type": "string"
    },
    "quote_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_payment",
        "paid",
        "in_progress",
        "awaiting_balance",
        "delivered",
        "confirmed",
        "disputed",
        "refunded",
        "cancelled"
      ],
      "description": "The only task statuses there are, in the usual order: awaiting_payment, paid, in_progress, delivered, confirmed (awaiting_balance with a deposit; disputed, refunded, cancelled). paid is not in_progress: the operator sets in_progress when the work starts, and delivered (not the parcel arriving) is what allows accepting with confirm_delivery."
    },
    "checkout_url": {
      "type": "string",
      "format": "uri",
      "description": "The payment link of the payment that is due now (GET /pay/{task_id}, signed; opening it redirects to a Stripe Checkout page). Present while status is awaiting_payment or awaiting_balance and the link is valid: 4 days from when the payment was created, 28 for a balance. Never present for a test order."
    },
    "checkout_expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "When checkout_url stops working. Present together with checkout_url."
    },
    "payments": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "kind",
          "amount",
          "currency",
          "status"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "full",
              "card_hold",
              "deposit",
              "balance"
            ]
          },
          "amount": {
            "type": "number"
          },
          "currency": {
            "type": "string",
            "enum": [
              "EUR",
              "USD"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting",
              "authorised",
              "paid",
              "released",
              "refunded",
              "simulated"
            ]
          },
          "checkout_url": {
            "type": "string",
            "format": "uri",
            "description": "The payment link, while this payment is awaiting and the link is valid."
          },
          "checkout_expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "invoice_url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "invoice_url": {
      "type": "string",
      "format": "uri"
    },
    "paid": {
      "type": "boolean",
      "description": "True when nothing is owed right now: a payment is settled (paid, card hold authorised, or simulated in a test order) and none is awaiting."
    },
    "quote_valid_until": {
      "type": "string",
      "format": "date"
    },
    "expected_ship_date": {
      "type": "string",
      "format": "date",
      "description": "The delivery or dispatch date stated in the quote."
    },
    "scope": {
      "type": "string",
      "description": "What was quoted, as stated in the quote."
    },
    "deliverables": {
      "type": "string",
      "description": "What you receive, as stated in the quote."
    },
    "next_action": {
      "type": "string",
      "description": "One or two sentences in English: what the agent or the client should do now."
    },
    "messages": {
      "$ref": "#/$defs/OperatorMessages"
    },
    "duplicate_ignored": {
      "type": "boolean",
      "description": "Present and true only in the answer to a POST whose message was ignored because the same text was already the newest message of the thread (sent within the last 10 minutes)."
    },
    "message_sent": {
      "type": "boolean",
      "description": "Present only in the answer to a POST with a message: true, the message was stored and e-mailed to the operator; false, it was NOT stored because the operator had written something you had not read yet (that message is in messages, now marked as read; next_action says so): send your answer again. Absent when the same text was ignored (duplicate_ignored) and in every plain status call."
    },
    "test_mode": {
      "type": "boolean",
      "description": "Present and true only for a test order: no payment link; the operator simulates the payment after the order is placed (until then nothing is paid or simulated); no invoice, no contract."
    },
    "performed_by": {
      "type": "string",
      "description": "Name of the person who did the work."
    },
    "updates": {
      "type": "array",
      "description": "The last 3 status changes and events, oldest first. status is the task status at the moment of that event (not the current one).",
      "items": {
        "type": "object",
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "status": {
            "type": "string"
          },
          "note": {
            "type": "string"
          }
        }
      }
    },
    "older_updates": {
      "type": "integer",
      "minimum": 1,
      "description": "How many earlier updates are not listed. Present only when there are any; every status change is also e-mailed to the contact address."
    },
    "evidence": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "media_type": {
            "type": "string"
          },
          "captured_at": {
            "type": "string",
            "format": "date-time"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          }
        }
      }
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "carrier": {
            "type": "string"
          },
          "tracking_number": {
            "type": "string"
          },
          "tracking_url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  },
  "$defs": {
    "OperatorMessages": {
      "type": "array",
      "description": "The thread with the operator, newest first: the operator's notes and your own replies (from: agent over REST; the MCP tools show your own replies as from: you). An operator message you have not been shown yet is always included, also in the answer to your own reply (a message of yours sent while it is unread is not stored: message_sent is false). Read the operator's message first, then reply: call get_status with message (POST with a JSON body over REST); e-mailing the tasks address with the quote_id in the subject also works.",
      "items": {
        "type": "object",
        "required": [
          "at",
          "from",
          "text"
        ],
        "properties": {
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "from": {
            "type": "string",
            "enum": [
              "operator",
              "agent"
            ]
          },
          "text": {
            "type": "string",
            "description": "Plain text, at most 2000 characters. Never HTML."
          }
        }
      }
    }
  }
}