Hands for Agents

What we do and do not do, refused categories, prices and how to pay, as a short summary. No authentication. Pass full=true only if you need the worked price examples, the full legal text or the marketplace comparison: it is many times larger.

{
  "type": "object",
  "properties": {
    "full": {
      "type": "boolean",
      "default": false,
      "description": "true for the complete document (same as /services.json); false (default) for a short summary."
    }
  }
}

Ask a human for a fixed-price quote. Not binding, nothing is charged. Required: description, email and name (the name of the person or company for the invoice); also delivery_address if a physical item is to be shipped, handed over or collected (one plain string: recipient, street, postcode and city, country; phone is optional, never ask the user for one). Put everything the user told you (quantity, material, colour, size, address) into the fields or into description and nothing else (no invented file names or checks); ask the user for what is missing. Send the fields flat, as in the examples. For name use the company or person from the shipping address (or the company the user gave); do not ask the user for it, ask only if there is neither. If the user gave an address, its country is the country (ISO 3166-1 alpha-2). A VAT id only if the user gave one: never guess or make one up. Never invent a quote_id or a status: a real quote_id starts with q_ and comes only from this tool's own response. Returns quote_id and access_token (plus nda_url and upload_url, to POST input files to). Tell the user to save the access_token now: it is shown once and is the only key to the quote and the task. If the access_token is lost: POST https://api.handsforagents.com/v1/quotes/{quote_id}/access-token (REST only, not a tool); a new one is sent to the contact e-mail. get_status cannot recover it. A human answers within 24 hours, every day: call get_status(id=quote_id) until the status is quoted or refused. No authentication. Shortest possible request: {"description":"Make 20 rubber gaskets, 60 mm outer diameter, black EPDM.","email":"[email protected]","name":"Example Inc."}. With a delivery address and an input file: {"description":"Make 20 rubber gaskets, 60 mm outer diameter, black EPDM.","email":"[email protected]","name":"Example Inc.","delivery_address":"Example GmbH, Musterstr. 1, 10115 Berlin, DE, +49 30 000000","input_files":["https://example.com/gasket-drawing.pdf"]}

{
  "type": "object",
  "properties": {
    "description": {
      "type": "string",
      "description": "What is to be done, plainly: everything the user told you (quantity, material, colour, size, tolerances, what counts as done).",
      "maxLength": 20000
    },
    "services": {
      "type": "array",
      "description": "Service ids, if you know them.",
      "items": {
        "type": "string",
        "enum": [
          "design",
          "make",
          "assemble",
          "measure",
          "test",
          "verify",
          "ship"
        ]
      }
    },
    "deliverables": {
      "type": "string",
      "description": "What you expect to receive. Optional; otherwise put it in description.",
      "maxLength": 5000
    },
    "deadline": {
      "type": "string",
      "description": "Latest acceptable delivery date, ISO 8601. Optional.",
      "format": "date",
      "maxLength": 32
    },
    "delivery_address": {
      "type": "string",
      "description": "Required for a physical shipment. One plain string: recipient, street, postcode and city, country (only what the user gave; never invent one); a phone number last is optional.",
      "maxLength": 1000
    },
    "input_files": {
      "type": "array",
      "description": "HTTPS URLs of input files (photos, sketch, STEP/STL model, PDF drawing). At most 20.",
      "items": {
        "type": "string",
        "maxLength": 2000,
        "pattern": "^https://"
      },
      "maxItems": 20
    },
    "currency": {
      "type": "string",
      "description": "EUR or USD. Default EUR.",
      "enum": [
        "EUR",
        "USD"
      ]
    },
    "email": {
      "type": "string",
      "description": "Contact e-mail of the operator; the quote goes here.",
      "format": "email",
      "maxLength": 254,
      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
    },
    "name": {
      "type": "string",
      "description": "Required. The name of the person or company for the invoice.",
      "minLength": 1,
      "maxLength": 200,
      "pattern": "^[^\\r\\n]+$"
    },
    "country": {
      "type": "string",
      "description": "Operator's country, ISO 3166-1 alpha-2, upper case. Optional.",
      "pattern": "^[A-Z]{2}$"
    },
    "vat_id": {
      "type": "string",
      "description": "VAT or tax id for the invoice, only if the user gave it; never guess. Optional.",
      "maxLength": 32
    },
    "agent_name": {
      "type": "string",
      "description": "Name of the agent or platform. Optional.",
      "maxLength": 200
    },
    "allow_anonymised_example": {
      "type": "boolean",
      "description": "Consent to publish this task as an anonymised example. Only true if the client explicitly agreed. Default false.",
      "default": false
    }
  },
  "required": [
    "description",
    "email",
    "name"
  ]
}

Accept a quote and the terms of service (quote_id, access_token, terms_accepted=true, terms_version as stated in the quote). Returns task_id and checkout_url, the payment link for the first payment (the full price or a card hold up to 150 EUR, the deposit above). Give it to the user or the operator to pay by card (Stripe Checkout); it is valid for 4 days. The contract is concluded when the payment is received or the hold authorised. A test order (test_mode true) has no checkout_url and no payment link: the operator will simulate the payment AFTER you order; right now nothing is paid or simulated. Then follow the task with get_status(id=task_id); keep the access_token. Report to the user only what this response says; do not add conclusions.

{
  "type": "object",
  "properties": {
    "quote_id": {
      "type": "string"
    },
    "terms_accepted": {
      "type": "boolean",
      "const": true,
      "description": "Acceptance of https://handsforagents.com/terms.html by the operator."
    },
    "terms_version": {
      "type": "string",
      "description": "Version of the terms being accepted, currently 2026-09-29."
    },
    "allow_anonymised_example": {
      "type": "boolean",
      "default": false,
      "description": "Optional. Consent to publish this task as an anonymised example (terms, section 10). Only true if the client explicitly agreed. Default false."
    },
    "access_token": {
      "type": "string",
      "description": "Token returned by request_quote."
    }
  },
  "required": [
    "quote_id",
    "terms_accepted",
    "terms_version",
    "access_token"
  ]
}

Status of a quote (id = quote_id) or a task (id = task_id). Call it after request_quote until the status is quoted or refused, after create_task to follow the task, and every time the user asks about the status or about messages from the service: earlier answers are outdated, never answer from memory. Read next_action: what to do now. Report to the user only what this response says; do not add conclusions. The answer is short (older_updates and older_messages count what is left out; messages are newest first, from operator or you); full=true returns everything. To answer an operator question, call get_status with message, once and only with what the user told you. Read the operator's message first, then reply: while it is unread, your message is NOT stored (message_sent: false) and the answer shows it; otherwise message_sent is true. The same text again within 10 minutes is ignored (duplicate_ignored: true). test_mode true marks a test order: nothing is paid or invoiced.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "quote_id or task_id."
    },
    "access_token": {
      "type": "string",
      "description": "Token returned by request_quote."
    },
    "message": {
      "type": "string",
      "description": "Optional reply to the operator: plain text, 1-2000 characters. Leave it out for a plain status check."
    },
    "full": {
      "type": "boolean",
      "default": false,
      "description": "true: the complete answer."
    }
  },
  "required": [
    "id",
    "access_token"
  ]
}

accepted=true closes the task and, for a card hold, captures it. accepted=false with a reason opens a dispute, answered by a human within 2 business days; it can be used at the evidence stage, before the balance is paid, as well as after delivery. Without either, the task counts as accepted 7 days after delivery. Report to the user only what this response says; do not add conclusions.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "string"
    },
    "accepted": {
      "type": "boolean"
    },
    "reason": {
      "type": "string",
      "description": "Required when accepted is false: what differs from the quote."
    },
    "access_token": {
      "type": "string",
      "description": "Token returned by request_quote."
    }
  },
  "required": [
    "task_id",
    "accepted",
    "access_token"
  ]
}