{
  "openapi": "3.1.0",
  "info": {
    "title": "Truce API",
    "version": "1.0.0",
    "description": "Start a Truce (neutral, private AI mediation) or a free 'Who's right?' for your user, and check its status. A human always sends the invite and signs. Do not use Truce for abuse, violence, threats, a child's safety or crimes. Humans have the final say: Truce only suggests; both people decide and sign. Agents act only for their own user, with consent."
  },
  "servers": [
    {
      "url": "https://trucehq.com"
    }
  ],
  "paths": {
    "/api/truces": {
      "post": {
        "operationId": "startTruce",
        "summary": "Start a Truce for a real disagreement",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "topic",
                  "name",
                  "statement",
                  "wants"
                ],
                "properties": {
                  "topic": {
                    "type": "string",
                    "description": "What the disagreement is about, in a few neutral words."
                  },
                  "name": {
                    "type": "string",
                    "description": "Your user's first name."
                  },
                  "otherName": {
                    "type": "string",
                    "description": "The other person's first name."
                  },
                  "statement": {
                    "type": "string",
                    "description": "Your user's side."
                  },
                  "wants": {
                    "type": "string",
                    "description": "What your user would like to happen."
                  },
                  "floor": {
                    "type": "string",
                    "description": "Private: the least your user could accept. Never shown to the other side."
                  },
                  "olive": {
                    "type": "string",
                    "description": "Optional kind note to the other person."
                  },
                  "email": {
                    "type": "string",
                    "description": "Optional email for updates."
                  },
                  "category": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "invite_url": {
                      "type": "string",
                      "description": "Send this to the other person."
                    },
                    "private_url": {
                      "type": "string",
                      "description": "Your user's private key. Keep secret."
                    },
                    "status_url": {
                      "type": "string"
                    },
                    "next": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/truces/{token}": {
      "get": {
        "operationId": "getTruceStatus",
        "summary": "Status of a Truce, by the sender's private token",
        "parameters": [
          {
            "name": "token",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status, proposal and signatures"
          }
        }
      }
    },
    "/api/whos-right": {
      "post": {
        "operationId": "startWhosRight",
        "summary": "Start a free 'Who's right?' for a light everyday argument",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "topic",
                  "nameA",
                  "nameB",
                  "sideA"
                ],
                "properties": {
                  "topic": {
                    "type": "string"
                  },
                  "nameA": {
                    "type": "string",
                    "description": "Your user's first name."
                  },
                  "nameB": {
                    "type": "string",
                    "description": "The other person's first name."
                  },
                  "sideA": {
                    "type": "string",
                    "description": "Your user's side."
                  },
                  "email": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created: invite_url and status_url"
          }
        }
      }
    },
    "/api/whos-right/{code}": {
      "get": {
        "operationId": "getWhosRightStatus",
        "summary": "Whether the other side answered, and the verdict",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status and verdict"
          }
        }
      },
      "post": {
        "operationId": "answerWhosRight",
        "summary": "For the other side's agent: give their side and get the verdict (consent required)",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "sideB",
                  "consent"
                ],
                "properties": {
                  "sideB": {
                    "type": "string"
                  },
                  "consent": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verdict"
          },
          "400": {
            "description": "Missing fields or consent"
          }
        }
      }
    },
    "/api/invites/{code}": {
      "get": {
        "operationId": "getInvite",
        "summary": "For the invited person's agent: who invited them, what about, still open",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invite"
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "post": {
        "operationId": "answerTruce",
        "summary": "For the invited person's agent: give their side in private (consent required)",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "statement",
                  "wants",
                  "consent"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "statement": {
                    "type": "string"
                  },
                  "wants": {
                    "type": "string"
                  },
                  "floor": {
                    "type": "string",
                    "description": "Private. Never shown to the other side."
                  },
                  "email": {
                    "type": "string"
                  },
                  "consent": {
                    "type": "boolean",
                    "description": "Must be true: the user asked the agent to answer and agreed to these words."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "private_url and status_url"
          },
          "400": {
            "description": "Missing fields or consent"
          },
          "409": {
            "description": "Already answered"
          }
        }
      }
    }
  }
}