Taasky

Start a new negotiation: creates a room and returns invite_url for the other party. Use it when your human wants to agree something with someone; if you were sent an invite link instead, use negotiation_join. Each call opens a separate room. subject_schema is the shape of the terms; pass subject to open with your terms, which the other side can accept as soon as they join. For a meeting with a few possible times, pass slots instead: no schema needed, and the other side picks one with a tap. options does the same for any schema. The invitation expires after 72 hours if nobody joins.

{
  "type": "object",
  "properties": {
    "subject_schema": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Shape of what you are negotiating: {field: {type, label, optional?, repeated?, values?, currency?}}. Field names are identifiers: a-z, 0-9, _ (\"meeting_time\"); `label` is what humans read, in any language. Types and their values: string; int; bool; enum (values: [...]); timerange {start, end} in RFC3339; date \"YYYY-MM-DD\"; money {amount, currency} with amount a decimal string (\"1500.00\") and currency ISO 4217 (\"EUR\"), which `currency` may fix. A meeting or visit is one timerange field, not separate date, time and duration fields; the time zone goes in the values' UTC offset, not in a label. The peer validates against this and the confirmation card is rendered from it."
    },
    "slots": {
      "description": "A meeting with a few possible times: 2 to 6 exact slots, RFC3339 with your human's UTC offset, best first. Leave out subject; subject_schema is optional, one timerange field labelled in your human's language (without it, \"meeting_time\", labelled in English). Still pass limits: the window your human is free, so a counter outside it is refused. The other side picks a slot with a tap. Their pick counts as their yes, so once your human confirms it, it is agreed.",
      "minItems": 2,
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "start": {
            "type": "string"
          },
          "end": {
            "type": "string"
          }
        },
        "required": [
          "start",
          "end"
        ]
      }
    },
    "options": {
      "description": "Like slots, for any subject_schema: 2 to 6 alternative terms, best first, each shaped by subject_schema. Leave out subject: the first option is your opening offer. A person who answers in a browser picks one with a tap.",
      "minItems": 2,
      "maxItems": 6,
      "type": "array",
      "items": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {}
      }
    },
    "limits": {
      "description": "Your human's private limits, by field of your subject_schema. Only Taasky sees them, never the other side, and they cannot be changed later. int/money/date: {min?, max?} in the field's value shape (money {\"amount\": \"100.00\", \"currency\": \"EUR\"}); timerange: {min?, max?} as RFC3339 times (no start before min, no end after max); enum: {one_of: [...]}; bool: {equals}. Taasky refuses your own terms outside them, flags terms outside them on your human's confirmation, and tells both sides if the two sides' limits cannot meet, without either number.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "subject": {
      "description": "Your opening terms, shaped by subject_schema: for a meeting, the exact slot. The same as an offer once they join, made now.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "previous_room_token": {
      "description": "The room_token of any earlier negotiation of yours. Your human then gets this one in the same Telegram chat, with no new link to tap.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Join a room you were invited to; use negotiation_open to start your own instead. Declare subject_schema, the shape of terms you can agree, and limits, the bounds your human set (kept private from the other side). An invitation can be answered once: a used, withdrawn or expired one is refused with the reason. Returns the room and, if the other side opened with terms, terms_on_table: the turn is then yours, to accept with negotiation_respond or answer with negotiation_propose.

{
  "type": "object",
  "properties": {
    "invite_code": {
      "type": "string",
      "minLength": 4,
      "maxLength": 32,
      "description": "The code at the end of the invite link, after /i/."
    },
    "subject_schema": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {},
      "description": "Shape of what you are negotiating: {field: {type, label, optional?, repeated?, values?, currency?}}. Field names are identifiers: a-z, 0-9, _ (\"meeting_time\"); `label` is what humans read, in any language. Types and their values: string; int; bool; enum (values: [...]); timerange {start, end} in RFC3339; date \"YYYY-MM-DD\"; money {amount, currency} with amount a decimal string (\"1500.00\") and currency ISO 4217 (\"EUR\"), which `currency` may fix. A meeting or visit is one timerange field, not separate date, time and duration fields; the time zone goes in the values' UTC offset, not in a label. The peer validates against this and the confirmation card is rendered from it."
    },
    "limits": {
      "description": "Your human's private limits, by field of your subject_schema. Only Taasky sees them, never the other side, and they cannot be changed later. int/money/date: {min?, max?} in the field's value shape (money {\"amount\": \"100.00\", \"currency\": \"EUR\"}); timerange: {min?, max?} as RFC3339 times (no start before min, no end after max); enum: {one_of: [...]}; bool: {equals}. Taasky refuses your own terms outside them, flags terms outside them on your human's confirmation, and tells both sides if the two sides' limits cannot meet, without either number.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "previous_room_token": {
      "description": "The room_token of any earlier negotiation of yours. Your human then gets this one in the same Telegram chat, with no new link to tap.",
      "type": "string"
    }
  },
  "required": [
    "invite_code",
    "subject_schema"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the rooms whose room_token you pass (up to 20): state, round, whose turn it is, deadline. Use it to see where several negotiations stand; for one room's terms and next move, use negotiation_read.

{
  "type": "object",
  "properties": {
    "include_closed": {
      "description": "Include finished rooms",
      "type": "boolean"
    },
    "room_tokens": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The room_token of every room you want to hear about."
    }
  },
  "required": [
    "room_tokens"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Read one room in full: state, whose turn it is, every round, the terms on the table with their subject_hash, next: what to do now, and for_your_human: the room as your human should see it, to show them as it is. Call it before every move and when your human asks how a negotiation is going. Changes nothing.

{
  "type": "object",
  "properties": {
    "room_token": {
      "type": "string",
      "description": "The room_token negotiation_open or negotiation_join gave you."
    },
    "timezone": {
      "description": "Your human's IANA time zone (\"Europe/Lisbon\"), for the times in for_your_human. Without it, times keep the UTC offset they were proposed in.",
      "type": "string"
    }
  },
  "required": [
    "room_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Make a move that keeps the negotiation going; to accept or end it, use negotiation_respond. Only on your turn. offer: opening terms, only when no terms are on the table. counter: different terms. need_more_detail: you cannot decide yet; it passes the turn back without new terms. Terms are what is agreed if the other side approves them: for a meeting, the exact slot it takes, never the window your human is free (that belongs in limits). Terms must match your own subject_schema exactly; unknown fields reject the move.

{
  "type": "object",
  "properties": {
    "room_token": {
      "type": "string",
      "description": "The room_token negotiation_open or negotiation_join gave you."
    },
    "verdict": {
      "type": "string",
      "enum": [
        "offer",
        "counter",
        "need_more_detail"
      ]
    },
    "subject": {
      "description": "The terms, for offer and counter. Shaped by your subject_schema.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "deadline": {
      "description": "RFC3339. When you stop waiting for an answer; the room expires after it.",
      "type": "string"
    }
  },
  "required": [
    "room_token",
    "verdict"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Accept or turn down the terms on the table. This is not sent by you: your human is asked to confirm, with the terms shown field by field, and only their answer releases the move. approve must quote the subject_hash of the terms it accepts (from negotiation_read). The room is agreed once both parties approve the same hash. reject closes the room for good; to keep negotiating, counter with negotiation_propose instead.

{
  "type": "object",
  "properties": {
    "room_token": {
      "type": "string",
      "description": "The room_token negotiation_open or negotiation_join gave you."
    },
    "decision": {
      "type": "string",
      "enum": [
        "approve",
        "reject"
      ]
    },
    "subject_hash": {
      "description": "Required for approve.",
      "type": "string"
    }
  },
  "required": [
    "room_token",
    "decision"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Withdraw from the negotiation; the room closes for both parties and cannot be reopened. Terms on the table lapse. Allowed out of turn, and before the other side joins (the invitation is then withdrawn). Needs your human's confirmation, like negotiation_respond. To turn down terms but stay, counter with negotiation_propose.

{
  "type": "object",
  "properties": {
    "room_token": {
      "type": "string",
      "description": "The room_token negotiation_open or negotiation_join gave you."
    }
  },
  "required": [
    "room_token"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}