{
  "openapi": "3.0.3",
  "info": {
    "title": "Pental API",
    "version": "1",
    "description": "The functions an API key calls, in the Pental portal and in our free reporting tool. A key signs in with three calls (rpc_api_key_exchange, the password grant, rpc_api_key_bind) and then calls api_v1_ functions with the session it signed in. Every call is a POST with a JSON body. The guide: https://pental.io/guides/pental-api"
  },
  "servers": [
    {
      "url": "{base}",
      "description": "Your API address, as the key's dialog shows it",
      "variables": {
        "base": {
          "default": "https://your-api-address"
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Sign in"
    },
    {
      "name": "Read"
    },
    {
      "name": "Write"
    }
  ],
  "components": {
    "securitySchemes": {
      "publishableKey": {
        "type": "apiKey",
        "in": "header",
        "name": "apikey",
        "description": "The publishable key, as the key's dialog shows it."
      },
      "session": {
        "type": "http",
        "scheme": "bearer",
        "description": "The access token of the session the key signed in and bound."
      }
    },
    "schemas": {
      "Refusal": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "PT and the HTTP status, as PT401."
          },
          "message": {
            "type": "string"
          },
          "details": {
            "type": "string",
            "description": "A short code: key_invalid, key_revoked, key_expired, key_suspended, not_a_key_session, session_ended, no_session, no_exchange, role_off, contractors_off, api_off, writes_off, read_only, browser, interactive_session, session_taken, not_allowed, not_found, changed, rate_limited, bad_request."
          },
          "hint": {
            "type": "string",
            "nullable": true
          }
        }
      }
    }
  },
  "paths": {
    "/rest/v1/rpc/api_v1_client_create": {
      "post": {
        "operationId": "api_v1_client_create",
        "summary": "Make a client",
        "description": "Makes a client. Its reference (job code) is given by the portal when it is next shown. Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_name": {
                    "type": "string"
                  },
                  "p_industry": {
                    "type": "string"
                  },
                  "p_contact_name": {
                    "type": "string"
                  },
                  "p_contact_email": {
                    "type": "string"
                  },
                  "p_contact_phone": {
                    "type": "string"
                  },
                  "p_address": {
                    "type": "string"
                  }
                },
                "required": [
                  "p_name"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_client_update": {
      "post": {
        "operationId": "api_v1_client_update",
        "summary": "Change a client",
        "description": "Changes a client's details. A parameter left out is left as it is; an empty string clears it. Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_client_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_row_version": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "p_name": {
                    "type": "string"
                  },
                  "p_industry": {
                    "type": "string"
                  },
                  "p_contact_name": {
                    "type": "string"
                  },
                  "p_contact_email": {
                    "type": "string"
                  },
                  "p_contact_phone": {
                    "type": "string"
                  },
                  "p_address": {
                    "type": "string"
                  }
                },
                "required": [
                  "p_client_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "changed": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_clients": {
      "post": {
        "operationId": "api_v1_clients",
        "summary": "Clients",
        "description": "Clients, by name, optionally only those whose name contains p_search or that changed since p_changed_since.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_search": {
                    "type": "string"
                  },
                  "p_changed_since": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "industry": {
                        "type": "string",
                        "nullable": true
                      },
                      "contact_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "contact_email": {
                        "type": "string",
                        "nullable": true
                      },
                      "contact_phone": {
                        "type": "string",
                        "nullable": true
                      },
                      "address": {
                        "type": "string",
                        "nullable": true
                      },
                      "status": {
                        "type": "string",
                        "nullable": true
                      },
                      "job_code": {
                        "type": "string",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_comment_add": {
      "post": {
        "operationId": "api_v1_comment_add",
        "summary": "Add a comment",
        "description": "Adds a comment to an engagement, or a reply with p_parent_id. Plain text. Shown to the client only with p_client_visible true (a client's own comment always is). Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_engagement_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_content": {
                    "type": "string"
                  },
                  "p_parent_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_client_visible": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "p_engagement_id",
                  "p_content"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "engagement_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "parent_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "client_visible": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_comments": {
      "post": {
        "operationId": "api_v1_comments",
        "summary": "Comments",
        "description": "An engagement's comments, or every engagement's, oldest first.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_engagement_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_changed_since": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "engagement_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "parent_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "author_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "author_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "author_role": {
                        "type": "string",
                        "nullable": true
                      },
                      "content": {
                        "type": "string",
                        "nullable": true
                      },
                      "client_visible": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_engagement_create": {
      "post": {
        "operationId": "api_v1_engagement_create",
        "summary": "Make an engagement",
        "description": "Makes an engagement for a client, pending, with the client's next reference, as the portal's New Assessment does. Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_client_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_name": {
                    "type": "string"
                  },
                  "p_start_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "p_end_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "p_type": {
                    "type": "string"
                  },
                  "p_lead_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_test_days": {
                    "type": "number"
                  },
                  "p_scope": {
                    "type": "string"
                  }
                },
                "required": [
                  "p_client_id",
                  "p_name",
                  "p_start_date",
                  "p_end_date"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "job_code": {
                        "type": "string",
                        "nullable": true
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "status": {
                        "type": "string",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_engagement_update": {
      "post": {
        "operationId": "api_v1_engagement_update",
        "summary": "Change an engagement",
        "description": "Changes an engagement's name, type, dates, lead, days or scope. A parameter left out is left as it is; p_clear_lead takes the lead off. Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_engagement_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_row_version": {
                    "type": "integer",
                    "format": "int64"
                  },
                  "p_name": {
                    "type": "string"
                  },
                  "p_type": {
                    "type": "string"
                  },
                  "p_start_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "p_end_date": {
                    "type": "string",
                    "format": "date"
                  },
                  "p_lead_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_clear_lead": {
                    "type": "boolean"
                  },
                  "p_test_days": {
                    "type": "number"
                  },
                  "p_scope": {
                    "type": "string"
                  }
                },
                "required": [
                  "p_engagement_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "changed": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_engagements": {
      "post": {
        "operationId": "api_v1_engagements",
        "summary": "Engagements",
        "description": "Engagements (assessments), newest first, with their client, lead and findings counted.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_client_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_status": {
                    "type": "string"
                  },
                  "p_changed_since": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "p_include_archived": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "client_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "client_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "type": {
                        "type": "string",
                        "nullable": true
                      },
                      "status": {
                        "type": "string",
                        "nullable": true
                      },
                      "qa_status": {
                        "type": "string",
                        "nullable": true
                      },
                      "job_code": {
                        "type": "string",
                        "nullable": true
                      },
                      "start_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                      },
                      "end_date": {
                        "type": "string",
                        "format": "date",
                        "nullable": true
                      },
                      "lead_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "lead_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "contractor_team_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "test_days": {
                        "type": "number",
                        "nullable": true
                      },
                      "scope": {
                        "type": "string",
                        "nullable": true
                      },
                      "phases": {
                        "nullable": true
                      },
                      "findings_total": {
                        "type": "integer",
                        "nullable": true
                      },
                      "findings_open": {
                        "type": "integer",
                        "nullable": true
                      },
                      "delivered_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "archived_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_files": {
      "post": {
        "operationId": "api_v1_files",
        "summary": "Files",
        "description": "What an engagement's files are (names, sizes, types), not their contents.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_engagement_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "engagement_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "file_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "file_size": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      },
                      "mime_type": {
                        "type": "string",
                        "nullable": true
                      },
                      "doc_type": {
                        "type": "string",
                        "nullable": true
                      },
                      "uploaded_by_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "uploaded_by_client": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "client_visible": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_finding_request_retest": {
      "post": {
        "operationId": "api_v1_finding_request_retest",
        "summary": "Ask for a retest",
        "description": "Asks for a retest of a finding that is open or part remediated, as the portal does. Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_finding_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "p_finding_id"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "retest_status": {
                        "type": "string",
                        "nullable": true
                      },
                      "retest_requested_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "already": {
                        "type": "boolean",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_finding_set_status": {
      "post": {
        "operationId": "api_v1_finding_set_status",
        "summary": "Set a finding's status",
        "description": "Sets a finding's status to open, remediated, part_remediated or accepted. With p_row_version, only if the finding has not changed since it was read (409 otherwise). Needs a key that writes, with writing switched on.",
        "tags": [
          "Write"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_finding_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_status": {
                    "type": "string"
                  },
                  "p_row_version": {
                    "type": "integer",
                    "format": "int64"
                  }
                },
                "required": [
                  "p_finding_id",
                  "p_status"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "status": {
                        "type": "string",
                        "nullable": true
                      },
                      "changed": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_findings": {
      "post": {
        "operationId": "api_v1_findings",
        "summary": "Findings",
        "description": "Findings, worst first within each engagement, with their fields but never their evidence. Description, impact and remediation are HTML.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_engagement_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_client_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_status": {
                    "type": "string"
                  },
                  "p_severity": {
                    "type": "string"
                  },
                  "p_changed_since": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "p_include_drafts": {
                    "type": "boolean"
                  },
                  "p_include_archived": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "engagement_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "client_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "finding_code": {
                        "type": "string",
                        "nullable": true
                      },
                      "title": {
                        "type": "string",
                        "nullable": true
                      },
                      "severity": {
                        "type": "string",
                        "nullable": true
                      },
                      "severity_rank": {
                        "type": "integer",
                        "nullable": true
                      },
                      "cvss": {
                        "type": "number",
                        "nullable": true
                      },
                      "cvss_vector": {
                        "type": "string",
                        "nullable": true
                      },
                      "status": {
                        "type": "string",
                        "nullable": true
                      },
                      "phase": {
                        "type": "string",
                        "nullable": true
                      },
                      "category": {
                        "type": "string",
                        "nullable": true
                      },
                      "cwe": {
                        "type": "string",
                        "nullable": true
                      },
                      "affected_hosts": {
                        "type": "string",
                        "nullable": true
                      },
                      "description": {
                        "type": "string",
                        "nullable": true
                      },
                      "impact": {
                        "type": "string",
                        "nullable": true
                      },
                      "remediation": {
                        "type": "string",
                        "nullable": true
                      },
                      "refs": {
                        "nullable": true
                      },
                      "custom_fields": {
                        "nullable": true
                      },
                      "is_draft": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "client_visible": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "retest_requested": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "retest_status": {
                        "type": "string",
                        "nullable": true
                      },
                      "retest_requested_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "retest_completed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "archived_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "updated_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "changed_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "row_version": {
                        "type": "integer",
                        "format": "int64",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_me": {
      "post": {
        "operationId": "api_v1_me",
        "summary": "Who the key is",
        "description": "The key's person, the key itself, the firm, and whether it may write now.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "person_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "email": {
                        "type": "string",
                        "nullable": true
                      },
                      "role": {
                        "type": "string",
                        "nullable": true
                      },
                      "job_title": {
                        "type": "string",
                        "nullable": true
                      },
                      "client_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "key_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "key_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "key_prefix": {
                        "type": "string",
                        "nullable": true
                      },
                      "key_scope": {
                        "type": "string",
                        "nullable": true
                      },
                      "key_expires_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      },
                      "firm": {
                        "type": "string",
                        "nullable": true
                      },
                      "api_version": {
                        "type": "string",
                        "nullable": true
                      },
                      "writes_enabled": {
                        "type": "boolean",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_people": {
      "post": {
        "operationId": "api_v1_people",
        "summary": "People",
        "description": "The people the key's person can see, active ones unless asked otherwise.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_include_inactive": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "name": {
                        "type": "string",
                        "nullable": true
                      },
                      "email": {
                        "type": "string",
                        "nullable": true
                      },
                      "role": {
                        "type": "string",
                        "nullable": true
                      },
                      "job_title": {
                        "type": "string",
                        "nullable": true
                      },
                      "active": {
                        "type": "boolean",
                        "nullable": true
                      },
                      "client_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "contractor_team_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_statuses": {
      "post": {
        "operationId": "api_v1_statuses",
        "summary": "Values",
        "description": "The values a status, severity or QA field may hold, each with a label to show.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "nullable": true
                      },
                      "value": {
                        "type": "string",
                        "nullable": true
                      },
                      "label": {
                        "type": "string",
                        "nullable": true
                      },
                      "rank": {
                        "type": "integer",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/api_v1_timeline": {
      "post": {
        "operationId": "api_v1_timeline",
        "summary": "Timeline",
        "description": "An engagement's timeline, or every engagement's, oldest first.",
        "tags": [
          "Read"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_engagement_id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "p_changed_since": {
                    "type": "string",
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "engagement_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "title": {
                        "type": "string",
                        "nullable": true
                      },
                      "by_id": {
                        "type": "string",
                        "format": "uuid",
                        "nullable": true
                      },
                      "by_name": {
                        "type": "string",
                        "nullable": true
                      },
                      "created_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/rpc_api_key_bind": {
      "post": {
        "operationId": "rpc_api_key_bind",
        "summary": "Sign in, step 3",
        "description": "Makes the session the exchange signed in the key's, within a minute of the exchange. Called with that session's access token. A key keeps its five newest sessions.",
        "tags": [
          "Sign in"
        ],
        "security": [
          {
            "publishableKey": [],
            "session": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_key": {
                    "type": "string"
                  }
                },
                "required": [
                  "p_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "key": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "name": {
                          "type": "string"
                        },
                        "prefix": {
                          "type": "string"
                        },
                        "scope": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": "string",
                          "format": "date-time"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    },
    "/rest/v1/rpc/rpc_api_key_exchange": {
      "post": {
        "operationId": "rpc_api_key_exchange",
        "summary": "Sign in, step 1",
        "description": "Exchanges a key for a single-use password and the address of the key's person. Called with the publishable key alone. Sign in with the two at /auth/v1/token?grant_type=password straight away.",
        "tags": [
          "Sign in"
        ],
        "security": [
          {
            "publishableKey": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "p_key": {
                    "type": "string"
                  }
                },
                "required": [
                  "p_key"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "email": {
                      "type": "string"
                    },
                    "password": {
                      "type": "string"
                    },
                    "expires_in": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "Refused: the status says why (400, 401, 403, 404, 409, 429), and the body's details holds a short code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Refusal"
                }
              }
            }
          }
        }
      }
    }
  }
}