Partner API reference.

{
  "operationId": "listinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/inventoryRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/inventoryCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/inventoryRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "getinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/inventoryRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateinventory",
  "tags": [
    "Vehicle inventory"
  ],
  "security": [
    {
      "partnerToken": [
        "inventory:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/inventoryUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/inventoryRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/leadsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/leadsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/leadsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "getleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/leadsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateleads",
  "tags": [
    "Leads"
  ],
  "security": [
    {
      "partnerToken": [
        "leads:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/leadsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/leadsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/clientsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/clientsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/clientsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "getclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/clientsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateclients",
  "tags": [
    "Customers"
  ],
  "security": [
    {
      "partnerToken": [
        "clients:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/clientsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/clientsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/serviceRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/serviceCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/serviceRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "getservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/serviceRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateservice",
  "tags": [
    "Repair orders"
  ],
  "security": [
    {
      "partnerToken": [
        "service:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/serviceUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/serviceRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/partsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/partsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/partsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "getparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/partsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateparts",
  "tags": [
    "Parts catalogue"
  ],
  "security": [
    {
      "partnerToken": [
        "parts:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/partsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/partsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Records ordered by ID",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/appointmentsRecord"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/appointmentsCreate"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/appointmentsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "getappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/appointmentsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateappointments",
  "tags": [
    "Sales appointments"
  ],
  "security": [
    {
      "partnerToken": [
        "appointments:update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/appointmentsUpdate"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Authorized record",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/appointmentsRecord"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "submitPartnerApplication",
  "description": "Exact allowed Origin and Turnstile action partner_application required. Submission grants no system access.",
  "security": [],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "company": {
              "type": "string",
              "maxLength": 160
            },
            "contact_name": {
              "type": "string",
              "maxLength": 160
            },
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            },
            "website": {
              "type": "string",
              "format": "uri",
              "maxLength": 500
            },
            "purpose": {
              "type": "string",
              "maxLength": 4000
            },
            "requested_scopes": {
              "type": "array",
              "minItems": 1,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "enum": [
                  "inventory:read",
                  "inventory:create",
                  "inventory:update",
                  "inventory:bulk",
                  "leads:read",
                  "leads:create",
                  "leads:update",
                  "leads:bulk",
                  "clients:read",
                  "clients:create",
                  "clients:update",
                  "clients:bulk",
                  "service:read",
                  "service:create",
                  "service:update",
                  "service:bulk",
                  "parts:read",
                  "parts:create",
                  "parts:update",
                  "parts:bulk",
                  "appointments:read",
                  "appointments:create",
                  "appointments:update",
                  "appointments:bulk",
                  "invoices:read",
                  "invoices:create",
                  "invoices:draft-update",
                  "payments:links",
                  "payments:read",
                  "payments:charge",
                  "payments:refund",
                  "events:subscribe",
                  "exports:create",
                  "media:read"
                ]
              }
            },
            "data_use": {
              "type": "string",
              "maxLength": 4000
            },
            "retention_days": {
              "type": "integer",
              "minimum": 0,
              "maximum": 3650
            },
            "turnstile": {
              "type": "string",
              "maxLength": 4096
            },
            "company_url": {
              "type": "string",
              "maxLength": 0
            },
            "details": {
              "type": "object",
              "properties": {
                "country": {
                  "type": "string",
                  "maxLength": 3000
                },
                "role": {
                  "type": "string",
                  "maxLength": 3000
                },
                "support": {
                  "type": "string",
                  "maxLength": 3000
                },
                "security": {
                  "type": "string",
                  "maxLength": 3000
                },
                "owners": {
                  "type": "string",
                  "maxLength": 3000
                },
                "app": {
                  "type": "string",
                  "maxLength": 3000
                },
                "model": {
                  "type": "string",
                  "maxLength": 3000
                },
                "execution": {
                  "type": "string",
                  "maxLength": 3000
                },
                "locations": {
                  "type": "string",
                  "maxLength": 3000
                },
                "demo": {
                  "type": "string",
                  "maxLength": 3000
                },
                "storage": {
                  "type": "string",
                  "maxLength": 3000
                },
                "retention": {
                  "type": "string",
                  "maxLength": 3000
                },
                "ai": {
                  "type": "string",
                  "maxLength": 3000
                },
                "incident": {
                  "type": "string",
                  "maxLength": 3000
                },
                "payments": {
                  "type": "string",
                  "maxLength": 3000
                },
                "paymentDetails": {
                  "type": "string",
                  "maxLength": 3000
                },
                "commercial": {
                  "type": "string",
                  "maxLength": 3000
                }
              },
              "required": [],
              "additionalProperties": false
            }
          },
          "required": [
            "company",
            "contact_name",
            "email",
            "website",
            "purpose",
            "requested_scopes",
            "data_use",
            "retention_days",
            "turnstile"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Stored application; manual screening pending",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "applicationId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "const": "submitted"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "exchangePartnerToken",
  "description": "Code with S256 PKCE or rotating refresh token. Confidential clients authenticate. Client credentials/password grants unavailable.",
  "security": [],
  "requestBody": {
    "required": true,
    "content": {
      "application/x-www-form-urlencoded": {
        "schema": {
          "type": "object",
          "properties": {
            "grant_type": {
              "enum": [
                "authorization_code",
                "refresh_token"
              ]
            },
            "client_id": {
              "type": "string",
              "format": "uuid"
            },
            "client_secret": {
              "type": "string",
              "writeOnly": true
            },
            "code": {
              "type": "string"
            },
            "code_verifier": {
              "type": "string",
              "minLength": 43,
              "maxLength": 128
            },
            "redirect_uri": {
              "type": "string",
              "format": "uri"
            },
            "refresh_token": {
              "type": "string",
              "writeOnly": true
            },
            "scope": {
              "type": "string"
            }
          },
          "required": [
            "grant_type"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Short-lived access token and rotated refresh token; store securely.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "access_token": {
                "type": "string"
              },
              "refresh_token": {
                "type": "string"
              },
              "expires_in": {
                "type": "integer"
              },
              "token_type": {
                "const": "Bearer"
              },
              "scope": {
                "type": "string"
              }
            },
            "required": []
          }
        }
      }
    },
    "400": {
      "description": "OAuth error"
    },
    "401": {
      "description": "Client authentication failed"
    },
    "503": {
      "description": "Partner access unavailable"
    }
  }
}

{
  "operationId": "requestPaymentlinks",
  "description": "Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.",
  "security": [
    {
      "partnerToken": [
        "payments:links"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invoiceId": {
              "type": "string",
              "maxLength": 128
            },
            "processorId": {
              "type": "string",
              "maxLength": 64
            },
            "amountMinor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999
            },
            "currency": {
              "const": "usd"
            }
          },
          "required": [
            "invoiceId",
            "processorId",
            "amountMinor",
            "currency"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reserved intent and current state; does not itself prove funds settled.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "202": {
      "description": "Exact refund needs dealership administrator approval; resubmit identical key after approval.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "requestPaymentcharges",
  "description": "Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.",
  "security": [
    {
      "partnerToken": [
        "payments:charge"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invoiceId": {
              "type": "string",
              "maxLength": 128
            },
            "processorId": {
              "type": "string",
              "maxLength": 64
            },
            "amountMinor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999
            },
            "currency": {
              "const": "usd"
            },
            "savedMethodId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "invoiceId",
            "processorId",
            "amountMinor",
            "currency",
            "savedMethodId"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reserved intent and current state; does not itself prove funds settled.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "202": {
      "description": "Exact refund needs dealership administrator approval; resubmit identical key after approval.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "requestPaymentrefunds",
  "description": "Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.",
  "security": [
    {
      "partnerToken": [
        "payments:refund"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invoiceId": {
              "type": "string",
              "maxLength": 128
            },
            "processorId": {
              "type": "string",
              "maxLength": 64
            },
            "amountMinor": {
              "type": "integer",
              "minimum": 1,
              "maximum": 99999999
            },
            "currency": {
              "const": "usd"
            },
            "parentId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "invoiceId",
            "processorId",
            "amountMinor",
            "currency",
            "parentId"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Reserved intent and current state; does not itself prove funds settled.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "202": {
      "description": "Exact refund needs dealership administrator approval; resubmit identical key after approval.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "readPayment",
  "security": [
    {
      "partnerToken": [
        "payments:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Payment belonging to this installation and dealership.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Payment"
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "cancelUnsubmittedPayment",
  "description": "Cancel only an unsubmitted reserved or approval-required intent owned by this installation. Idempotent when already canceled. Submitted processor effects require reconciliation and cannot be canceled through this endpoint. Requires the matching link/charge/refund permission and current actor permissions.",
  "security": [
    {
      "partnerToken": [
        "payments:links"
      ]
    },
    {
      "partnerToken": [
        "payments:charge"
      ]
    },
    {
      "partnerToken": [
        "payments:refund"
      ]
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "operation": {
              "enum": [
                "link",
                "charge",
                "refund"
              ]
            }
          },
          "required": [
            "operation"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Intent canceled without deleting records",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "state": {
                    "const": "canceled"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listSubscriptions",
  "security": [
    {
      "partnerToken": [
        "events:subscribe"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Current installation subscriptions; operational controls still being completed.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "resources": {
                      "type": "array",
                      "items": {
                        "enum": [
                          "inventory",
                          "leads",
                          "clients",
                          "service",
                          "parts",
                          "appointments",
                          "invoices",
                          "payments"
                        ]
                      }
                    },
                    "endpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "status": {
                      "enum": [
                        "active",
                        "disabled"
                      ]
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": []
                },
                "maxItems": 100
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createSubscription",
  "description": "Reviewed webhook origin, events:subscribe and each resource:read required. Only future events are sent. Secret shown once; keep it server-side. Event envelopes contain references only; fetch records through authorized API.",
  "security": [
    {
      "partnerToken": [
        "events:subscribe"
      ]
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "endpoint": {
              "type": "string",
              "format": "uri"
            },
            "resources": {
              "type": "array",
              "minItems": 1,
              "uniqueItems": true,
              "items": {
                "enum": [
                  "inventory",
                  "leads",
                  "clients",
                  "service",
                  "parts",
                  "appointments",
                  "invoices",
                  "payments"
                ]
              }
            }
          },
          "required": [
            "endpoint",
            "resources"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Subscription signing secret shown once",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "const": "active"
                  },
                  "signingSecret": {
                    "type": "string"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listInvoices",
  "security": [
    {
      "partnerToken": [
        "invoices:read"
      ]
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "maxLength": 128
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Invoices for the authorized dealership",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Invoice"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "limit": {
                    "type": "integer"
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createInvoice",
  "description": "Platform allocates an APP-prefixed number in a separate namespace. Customer-only draft lines, USD minor units; no receipts, secrets or arbitrary customer names supplied by the app.",
  "security": [
    {
      "partnerToken": [
        "invoices:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "clientId": {
              "type": "string",
              "maxLength": 128
            },
            "department": {
              "enum": [
                "Vehicles",
                "Service",
                "Parts"
              ]
            },
            "lines": {
              "type": "array",
              "minItems": 1,
              "maxItems": 100,
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "enum": [
                      "Labor",
                      "Part",
                      "Fee",
                      "Discount",
                      "Tax"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "qty": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 10000,
                    "multipleOf": 0.001
                  },
                  "unitAmountMinor": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 99999999
                  }
                },
                "required": [
                  "kind",
                  "name",
                  "qty",
                  "unitAmountMinor"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "clientId",
            "department",
            "lines"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Customer-facing invoice projection; no internal/warranty lines, notes or payment credentials.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Invoice"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "readInvoice",
  "security": [
    {
      "partnerToken": [
        "invoices:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Customer-facing invoice projection; no internal/warranty lines, notes or payment credentials.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Invoice"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "replaceInvoiceDraft",
  "description": "Replace all draft lines and customer/department for a draft created by this installation. Requires current ETag; sent, paid, voided or payment-linked invoices are locked. No deletion or adjustment capability is implied.",
  "security": [
    {
      "partnerToken": [
        "invoices:draft-update"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    },
    {
      "in": "header",
      "name": "If-Match",
      "required": true,
      "schema": {
        "type": "string",
        "pattern": "^\"[1-9][0-9]*\"$"
      },
      "description": "ETag from last GET. Stale updates return 409."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "clientId": {
              "type": "string",
              "maxLength": 128
            },
            "department": {
              "enum": [
                "Vehicles",
                "Service",
                "Parts"
              ]
            },
            "lines": {
              "type": "array",
              "minItems": 1,
              "maxItems": 100,
              "items": {
                "type": "object",
                "properties": {
                  "kind": {
                    "enum": [
                      "Labor",
                      "Part",
                      "Fee",
                      "Discount",
                      "Tax"
                    ]
                  },
                  "name": {
                    "type": "string",
                    "maxLength": 200
                  },
                  "qty": {
                    "type": "number",
                    "exclusiveMinimum": 0,
                    "maximum": 10000,
                    "multipleOf": 0.001
                  },
                  "unitAmountMinor": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 99999999
                  }
                },
                "required": [
                  "kind",
                  "name",
                  "qty",
                  "unitAmountMinor"
                ],
                "additionalProperties": false
              }
            }
          },
          "required": [
            "clientId",
            "department",
            "lines"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Customer-facing invoice projection; no internal/warranty lines, notes or payment credentials.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "$ref": "#/components/schemas/Invoice"
              }
            },
            "required": []
          }
        }
      },
      "headers": {
        "ETag": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "readSubscriptionDeliveryHistory",
  "description": "Latest100 delivery summaries for this installation subscription; no payload snapshots.",
  "security": [
    {
      "partnerToken": [
        "events:subscribe"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Delivery summaries",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "object",
                  "properties": {
                    "event_id": {
                      "type": "integer"
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "sending",
                        "delivered",
                        "retry",
                        "dead",
                        "canceled"
                      ]
                    },
                    "attempts": {
                      "type": "integer"
                    },
                    "next_attempt_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "response_code": {
                      "type": [
                        "integer",
                        "null"
                      ]
                    }
                  },
                  "required": []
                }
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "updateSubscription",
  "security": [
    {
      "partnerToken": [
        "events:subscribe"
      ]
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "action": {
              "enum": [
                "disable",
                "rotate-secret"
              ]
            }
          },
          "required": [
            "action"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Subscription change; rotation immediately replaces the signing secret. Resource read permissions are required to rotate.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "status": {
                    "enum": [
                      "active",
                      "disabled"
                    ]
                  },
                  "signingSecret": {
                    "type": "string",
                    "description": "Present only after rotation; shown once."
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createExport",
  "description": "Bounded synchronous export capture. Requires exports:create AND resource:read; 1–500 records, 2 MiB output, 15-minute private artifact. Reuse key for retries. Ordered by ID; next cursor is provided on download. No caller-selected fields, arbitrary filters or public storage URLs.",
  "security": [
    {
      "partnerToken": [
        "exports:create"
      ]
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "resource": {
              "enum": [
                "inventory",
                "leads",
                "clients",
                "service",
                "parts",
                "appointments"
              ]
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            },
            "after": {
              "type": "string",
              "maxLength": 128,
              "default": ""
            }
          },
          "required": [
            "resource"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Ready export job",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "enum": [
                      "export",
                      "bulk"
                    ]
                  },
                  "resource": {
                    "enum": [
                      "inventory",
                      "leads",
                      "clients",
                      "service",
                      "parts",
                      "appointments"
                    ]
                  },
                  "status": {
                    "enum": [
                      "ready",
                      "canceled",
                      "expired"
                    ]
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "result": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Bulk item outcomes; exports use the protected download route."
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "executeBulk",
  "description": "Synchronous batch of 1–25 resource creates/updates. Requires resource:bulk plus every requested action scope and current actor permissions. Each successful item commits with its own version check; failures have safe per-item codes. No delete or financial operations. Whole-body schema validation precedes writes. Retry the same key/body to obtain the same results. Canceling or expiring the result never reverses writes.",
  "security": [
    {
      "partnerToken": []
    }
  ],
  "parameters": [
    {
      "in": "header",
      "name": "Idempotency-Key",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 128,
        "pattern": "^[A-Za-z0-9._:-]+$"
      },
      "description": "Generate once per intent and reuse only with the same request."
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "resource": {
              "enum": [
                "inventory",
                "leads",
                "clients",
                "service",
                "parts",
                "appointments"
              ]
            },
            "items": {
              "type": "array",
              "minItems": 1,
              "maxItems": 25,
              "items": {
                "anyOf": [
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "create"
                      },
                      "input": {
                        "$ref": "#/components/schemas/inventoryCreate"
                      }
                    },
                    "required": [
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "update"
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "input": {
                        "$ref": "#/components/schemas/inventoryUpdate"
                      }
                    },
                    "required": [
                      "operation",
                      "id",
                      "version",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "create"
                      },
                      "input": {
                        "$ref": "#/components/schemas/leadsCreate"
                      }
                    },
                    "required": [
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "update"
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "input": {
                        "$ref": "#/components/schemas/leadsUpdate"
                      }
                    },
                    "required": [
                      "operation",
                      "id",
                      "version",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "create"
                      },
                      "input": {
                        "$ref": "#/components/schemas/clientsCreate"
                      }
                    },
                    "required": [
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "update"
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "input": {
                        "$ref": "#/components/schemas/clientsUpdate"
                      }
                    },
                    "required": [
                      "operation",
                      "id",
                      "version",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "create"
                      },
                      "input": {
                        "$ref": "#/components/schemas/serviceCreate"
                      }
                    },
                    "required": [
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "update"
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "input": {
                        "$ref": "#/components/schemas/serviceUpdate"
                      }
                    },
                    "required": [
                      "operation",
                      "id",
                      "version",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "create"
                      },
                      "input": {
                        "$ref": "#/components/schemas/partsCreate"
                      }
                    },
                    "required": [
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "update"
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "input": {
                        "$ref": "#/components/schemas/partsUpdate"
                      }
                    },
                    "required": [
                      "operation",
                      "id",
                      "version",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "create"
                      },
                      "input": {
                        "$ref": "#/components/schemas/appointmentsCreate"
                      }
                    },
                    "required": [
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "operation": {
                        "const": "update"
                      },
                      "id": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 128
                      },
                      "version": {
                        "type": "integer",
                        "minimum": 1
                      },
                      "input": {
                        "$ref": "#/components/schemas/appointmentsUpdate"
                      }
                    },
                    "required": [
                      "operation",
                      "id",
                      "version",
                      "input"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            }
          },
          "required": [
            "resource",
            "items"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Ready bulk job with item outcomes",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "enum": [
                      "export",
                      "bulk"
                    ]
                  },
                  "resource": {
                    "enum": [
                      "inventory",
                      "leads",
                      "clients",
                      "service",
                      "parts",
                      "appointments"
                    ]
                  },
                  "status": {
                    "enum": [
                      "ready",
                      "canceled",
                      "expired"
                    ]
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "result": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Bulk item outcomes; exports use the protected download route."
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "readJob",
  "description": "Only the creating installation, consent version and actor/OAuth family can read the job. Refresh in that family works; a separate authorization does not inherit the artifact. Live operation permissions are rechecked.",
  "security": [
    {
      "partnerToken": []
    }
  ],
  "responses": {
    "200": {
      "description": "Job metadata and available bulk outcomes",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "enum": [
                      "export",
                      "bulk"
                    ]
                  },
                  "resource": {
                    "enum": [
                      "inventory",
                      "leads",
                      "clients",
                      "service",
                      "parts",
                      "appointments"
                    ]
                  },
                  "status": {
                    "enum": [
                      "ready",
                      "canceled",
                      "expired"
                    ]
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "result": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Bulk item outcomes; exports use the protected download route."
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "cancelJobResult",
  "description": "Permanently clears the export/bulk result; completed writes remain. Disconnection or re-consent also clears results. Artifact expiry denies download immediately; cleanup must be scheduled.",
  "security": [
    {
      "partnerToken": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "action": {
              "const": "cancel"
            }
          },
          "required": [
            "action"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Canceled result",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "kind": {
                    "enum": [
                      "export",
                      "bulk"
                    ]
                  },
                  "resource": {
                    "enum": [
                      "inventory",
                      "leads",
                      "clients",
                      "service",
                      "parts",
                      "appointments"
                    ]
                  },
                  "status": {
                    "enum": [
                      "ready",
                      "canceled",
                      "expired"
                    ]
                  },
                  "expiresAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "result": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Bulk item outcomes; exports use the protected download route."
                  }
                },
                "required": []
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "downloadExport",
  "description": "Authenticated JSONL; exports:create and source resource:read required at download. No CSV formula interpretation. Expires after 15 minutes, and revoked grants/families, re-consent or disconnection deny access. X-CarSoft-Next-Cursor identifies the next bounded capture when more records exist.",
  "security": [
    {
      "partnerToken": [
        "exports:create"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Private attachment containing one approved record per line.",
      "headers": {
        "X-CarSoft-Next-Cursor": {
          "schema": {
            "type": "string"
          }
        }
      },
      "content": {
        "application/x-ndjson": {
          "schema": {
            "type": "string"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listVehicleGalleryPhotos",
  "description": "Existing inventory marketing gallery only, at most 25 entries. Separate media:read and inventory:read approval/consent plus current actor inventory permission required. No storage paths, signed URLs, filenames, private documents, staff photos or arbitrary query fields.",
  "security": [
    {
      "partnerToken": [
        "media:read",
        "inventory:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Approved gallery references",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "maxItems": 25,
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "vehicleId": {
                      "type": "string"
                    },
                    "cover": {
                      "type": "boolean"
                    },
                    "download": {
                      "type": "string",
                      "description": "Authenticated relative API path; not a public signed storage URL."
                    }
                  },
                  "required": [
                    "id",
                    "vehicleId",
                    "cover",
                    "download"
                  ]
                }
              }
            },
            "required": []
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "downloadVehicleGalleryPhoto",
  "description": "Private no-store JPEG attachment from the exact tenant/vehicle/photo reference. Permissions and reference are checked again after provider read/re-encoding. Provider redirects are rejected, input bounded to 3 MiB/40 million pixels, supported JPEG/PNG/WebP re-encoded to at most 1600px with metadata stripped. Provider deadline 10 seconds; image processing budget 5 seconds excluding thread wait; at most four concurrent downloads per runtime instance. These technical safeguards cannot determine whether a dealership placed sensitive content in its marketing gallery; approved use and review obligations still apply. Upload/replacement/deletion and other attachment classes are unfinished/excluded.",
  "security": [
    {
      "partnerToken": [
        "media:read",
        "inventory:read"
      ]
    }
  ],
  "responses": {
    "200": {
      "description": "Authenticated JPEG attachment.",
      "content": {
        "image/jpeg": {
          "schema": {
            "type": "string",
            "format": "binary"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "readDeveloperIdentity",
  "description": "Separate provider-authenticated identity with verified email and TOTP MFA. Lists up to 100 active memberships for this identity. Dealership cookies and partner app OAuth tokens are rejected. No platform/dealership authority is granted.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listDeveloperApps",
  "description": "Organization-scoped apps and latest approved manifest only. Excludes platform review evidence, dealership data and credentials. Active owner/admin/developer/support membership required.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "registerDeveloperApp",
  "description": "Recent TOTP MFA and active owner/admin/developer membership required. Registers an unpublished draft only, without an executable revision, client or installation. Exact UUID requestId/body retries return the original app and its current status; changed reuse is rejected. At most 100 apps per organization; contact platform support at the ceiling.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 160,
              "description": "Trimmed app name."
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "organizationId",
            "name",
            "requestId"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listDeveloperSubmissions",
  "description": "Immutable proposed app changes and shared decisions for one organization. Excludes private platform review evidence. Active owner/admin/developer/support membership required.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "submitDeveloperUpdate",
  "description": "Recent TOTP confirmation (within ten minutes) and active owner/admin/developer membership required. Records the exact manifest for manual review; creates no executable revision or dealership grant. UUID requestId is an original-result retry receipt. Changes to pricing/access/data use need a new submission. Base revision must be current. An initial app uses explicit null before any approved revision exists; manual approval publishes revision 1 atomically, after domain verification. No credentials or dealership installation are created. Rejected/changes-requested proposals remain immutable and require a new request.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "appId": {
              "type": "string",
              "format": "uuid"
            },
            "baseRevisionId": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Explicit null for first-app proposals; otherwise current approved revision UUID."
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            },
            "sourceReference": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1000
            },
            "manifest": {
              "type": "object",
              "description": "Exact proposed description, data_use, retention_days/exceptions, pricing, platform_charges, scopes, field_policy, embedded_origin, locations, redirects and webhook_origins. Unknown fields and platform review_evidence are rejected. At most 64 KiB, inside the request body limit."
            }
          },
          "required": [
            "organizationId",
            "appId",
            "baseRevisionId",
            "requestId",
            "sourceReference",
            "manifest"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listDeveloperMembers",
  "description": "Active organization membership required. Returns developer member identifiers, roles/status/epochs; never dealership staff or secrets.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "changeDeveloperMembership",
  "description": "Recent MFA and current owner/admin membership required. Expected epoch prevents stale overwrites. Admins cannot manage peer admins or owners; owner changes remain platform-reviewed. Revocation immediately denies developer API access. Membership revocation or role change retires clients whose current secret was issued to that member, plus untracked platform-issued clients when a technical member changes access. Other known holders are preserved. Pending organization invitations issued by a changed member are permanently revoked. Reissue credentials and obtain fresh dealer OAuth after revocation.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "memberId": {
              "type": "string",
              "format": "uuid"
            },
            "epoch": {
              "type": "integer",
              "minimum": 1
            },
            "role": {
              "type": "string",
              "enum": [
                "admin",
                "developer",
                "billing",
                "support"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "revoked"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "memberId",
            "epoch",
            "role",
            "status",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listTeamInvitations",
  "description": "Active organization owner/admin membership required. Paginated metadata includes review_origin (platform or organization), issuer member ID and database-clock status. No token hash, invitation token or private evidence is returned.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "inviteTeamMember",
  "description": "Recent TOTP MFA and active owner/admin membership required. Owners can invite admin/developer/billing/support; admins can invite developer/billing/support. No owner invitations or platform-review impersonation. Exact UUID requestId/body retries recover metadata, without re-exposing or replacing the token; changed reuse conflicts. At most 50 pending unexpired platform/team invitations per organization. The token is shown once on fresh creation, stored only as a hash, bound to verified email and expires in seven days. Share securely; no automatic email is sent. Existing membership cannot be overwritten on acceptance.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "email": {
              "type": "string",
              "format": "email",
              "maxLength": 254
            },
            "role": {
              "type": "string",
              "enum": [
                "admin",
                "developer",
                "billing",
                "support"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            }
          },
          "required": [
            "organizationId",
            "email",
            "role",
            "reason",
            "requestId"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "revokeTeamInvitation",
  "description": "Recent TOTP MFA and owner/admin membership required. Owners can revoke ordinary team invitations; admins cannot revoke admin invitations. Platform-reviewed bootstrap/owner invitations are excluded. Repeated revocation succeeds; consumed invitations cannot be revoked. Acceptance serializes with issuer changes and invitation revocation.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "invitationId": {
              "type": "string",
              "format": "uuid"
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "invitationId",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "acceptDeveloperInvitation",
  "description": "One-use, seven-day invitation bound to the provider-verified email. Platform-reviewed bootstrap invitations and organization-issued ordinary team invitations preserve separate provenance. Organization invitations also require current issuer membership/epoch/role and live provider eligibility; offboarding or role changes revoke pending invitations. Requires recent TOTP MFA. Replay, expiry, revocation, wrong email and existing membership are rejected. Acceptance grants only organization membership; no automatic app approval or dealership credentials.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invitation": {
              "type": "string",
              "pattern": "^csdi_[A-Za-z0-9_-]{43}$"
            }
          },
          "required": [
            "invitation"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listDeveloperCredentials",
  "description": "Owner/admin/developer can read organization-scoped client metadata and versioned redirects/status. Secret values/hashes and current-secret custody records are excluded.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "createDeveloperClient",
  "description": "Owner/admin and recent TOTP MFA required. App/revision/redirects must be approved and domains currently verified. At most 20 active clients per app. Creates a hashed backend secret and records the current recipient for offboarding; plaintext appears only in this response. This never authorizes a dealership. A UUID requestId provides deterministic original-client recovery after a lost response. An exact retry returns only that client metadata with secretUnavailable, never plaintext; revoke and deliberately replace it if the original secret was lost.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "appId": {
              "type": "string",
              "format": "uuid"
            },
            "revisionId": {
              "type": "string",
              "format": "uuid"
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            },
            "redirects": {
              "type": "array",
              "minItems": 1,
              "maxItems": 20,
              "uniqueItems": true,
              "items": {
                "type": "string",
                "format": "uri",
                "maxLength": 500
              }
            }
          },
          "required": [
            "organizationId",
            "appId",
            "revisionId",
            "redirects",
            "requestId"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Exact receipt retry returns metadata; no secret is recovered.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "credentialVersion": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "revoked"
                    ]
                  },
                  "secretUnavailable": {
                    "type": "boolean",
                    "const": true
                  }
                },
                "required": [
                  "clientId",
                  "credentialVersion",
                  "status",
                  "secretUnavailable"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      }
    },
    "201": {
      "description": "One-time credential response. No-store.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "clientSecret": {
                    "type": "string"
                  },
                  "credentialVersion": {
                    "type": "integer",
                    "const": 1
                  },
                  "status": {
                    "type": "string",
                    "const": "active"
                  }
                },
                "required": [
                  "clientId",
                  "clientSecret",
                  "credentialVersion",
                  "status"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "changeDeveloperClient",
  "description": "Owner/admin and recent TOTP MFA required. Expected credentialVersion prevents concurrent overwrite. Rotation invalidates old secrets/codes/families and transfers current-secret custody; requires active app/domain proof. Revocation is permanent and remains possible for a suspended app. Lists never recover plaintext secrets. A lost mutation response requires rereading metadata and deliberately reconciling/replacing credentials, never blind replay.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "clientId": {
              "type": "string",
              "format": "uuid"
            },
            "credentialVersion": {
              "type": "integer",
              "minimum": 1
            },
            "decision": {
              "type": "string",
              "enum": [
                "rotate",
                "revoke"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "clientId",
            "credentialVersion",
            "decision",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "One-time credential mutation response. No-store.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "clientId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "credentialVersion": {
                    "type": "integer",
                    "minimum": 2
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "revoked"
                    ]
                  },
                  "clientSecret": {
                    "type": "string",
                    "description": "Only on successful rotation; never readable later."
                  }
                },
                "required": [
                  "clientId",
                  "credentialVersion",
                  "status"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listCredentialSharing",
  "description": "Active owner/admin/developer organization membership required. Paginated immutable sharing requests/status/decision notes exclude secret hashes and private review evidence. Database clock determines expiry.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "requestCredentialSharing",
  "description": "Recent TOTP MFA and active owner/admin membership required. Issuer must already be a recorded holder of the exact current client secret. Recipient must be another active owner/admin/developer in the same organization. Bind both membership epochs and current credentialVersion. Requires an approved app/current domain proof. Original UUID requestId/body retries recover request metadata; changed reuse conflicts. Seven-day requests, one live request per client/recipient and at most 50 per organization. Creates no custody/access and never receives, reveals or delivers a client secret. Share only after recipient acceptance and platform approval; use a secure channel outside this API.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "clientId": {
              "type": "string",
              "format": "uuid"
            },
            "recipientMemberId": {
              "type": "string",
              "format": "uuid"
            },
            "issuerEpoch": {
              "type": "integer",
              "minimum": 1
            },
            "recipientEpoch": {
              "type": "integer",
              "minimum": 1
            },
            "credentialVersion": {
              "type": "integer",
              "minimum": 1
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "clientId",
            "recipientMemberId",
            "issuerEpoch",
            "recipientEpoch",
            "credentialVersion",
            "requestId",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "respondCredentialSharing",
  "description": "Recent TOTP MFA and active technical membership required. Only the recipient accepts/declines; only issuer cancels, using exact shareId/fingerprint. Acceptance grants no custody/access. Platform admin must separately review both live provider identities and exact immutable request with password/evidence; SQL rechecks epochs, client version/digest, issuer custody, approval/domain proof and expiry. Approval adds recipient to current-secret custody without changing OAuth credentials/tokens/dealer consent. Offboarding any recorded current holder permanently retires the shared client. Knowledge cannot be removed by deleting a holder record; rotate/revoke instead. Closed history is immutable.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "shareId": {
              "type": "string",
              "format": "uuid"
            },
            "fingerprint": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "decision": {
              "type": "string",
              "enum": [
                "accept",
                "decline",
                "cancel"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "shareId",
            "fingerprint",
            "decision",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listOwnershipRequests",
  "description": "Organization-scoped ownership request history for active members; fixed pagination. Excludes private identity/business review evidence. Database time presents expired requests as expired.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "requestOwnershipTransfer",
  "description": "Current owner with recent TOTP MFA requests transfer of their owner role to an active non-owner member in the same organization. Both current membership epochs are required. The request expires in seven days; only one live request per outgoing owner. Original requestId retries return the same request and current status; changed reuse conflicts. No role, app credential or dealership access changes on creation.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "incomingMemberId": {
              "type": "string",
              "format": "uuid"
            },
            "outgoingEpoch": {
              "type": "integer",
              "minimum": 1
            },
            "incomingEpoch": {
              "type": "integer",
              "minimum": 1
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "incomingMemberId",
            "outgoingEpoch",
            "incomingEpoch",
            "requestId",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "respondOwnershipTransfer",
  "description": "Recent TOTP MFA and the exact immutable fingerprint required. Only incoming member may accept/decline; only outgoing member may cancel. Acceptance rechecks both current memberships/epochs, does not promote anyone and needs platform review afterward. Cancellation/decline can close stale membership proposals while the responding identity still has active organization membership. Repeated acceptance returns accepted until request closes or expires. Partners cannot approve. Platform approval requires both confirmations, current epochs, live provider identity/email/MFA checks (shared six-second deadline) and recorded identity/business evidence; it revokes outgoing membership and affected credentials, increments both epochs and preserves dealership consent. Clients held only by other known holders remain active; no new clients or dealer access are created.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "transferId": {
              "type": "string",
              "format": "uuid"
            },
            "fingerprint": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "decision": {
              "type": "string",
              "enum": [
                "accept",
                "decline",
                "cancel"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "transferId",
            "fingerprint",
            "decision",
            "reason"
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listPartnerBillingAgreements",
  "description": "Active organization owner/admin/billing membership and verified TOTP identity required. Immutable platform-offered monthly commercial terms and exact fingerprints, acceptance/decision metadata and database-clock offer expiry. UUID keyset pagination; private review evidence excluded. Partners collect their own fees; CarSoft bills its agreed fees through its existing Stripe account. No automatic suspension for overdue invoices.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "respondPartnerBillingAgreement",
  "description": "Only a current organization owner with recent TOTP MFA may accept or decline the exact platform offer. Exact fingerprint and reason required. Fourteen-day expiry, future start date and one accepted agreement per calendar month are enforced. Subsequent prices begin at a future calendar month. Accepted commercial terms are immutable; same-owner acceptance retries recover accepted status. Acceptance creates no invoice, charge, credential or dealership permission. Overdue collection decisions remain with the platform administrator.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "agreementId": {
              "type": "string",
              "format": "uuid"
            },
            "fingerprint": {
              "type": "string",
              "pattern": "^[a-f0-9]{64}$"
            },
            "decision": {
              "type": "string",
              "enum": [
                "accept",
                "decline"
              ]
            },
            "reason": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4000
            }
          },
          "required": [
            "organizationId",
            "agreementId",
            "fingerprint",
            "decision",
            "reason"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listPartnerFeePeriods",
  "description": "Read-only immutable completed UTC calendar-month calculations for active owner/admin/billing members with verified TOTP identity. Successful production app API requests are metered once per generated server request ID. OAuth, developer identity requests, denied/failed responses and sandbox calls are not billed. Installation days use positive active UTC-day overlap and deduplicate restarts; evidence begins when tracking is installed, without backfilled historical usage. Revenue share requires a platform-reviewed statement for the exact agreed window/currency, including explicit zero. Before freezing, reviewed corrections preserve prior statements; after freezing, a separate adjustment is required. Exact retries recover the same period. No invoice or paid revenue is created by freezing. Release-gated invoice issuance/reconciliation workers and durable manual-decision notices are locally implemented. Automatic monthly scheduling and signed provider events are locally implemented; cancellation and credits remain unfinished; local protocol fixtures are not actual Stripe sandbox acceptance.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Exact monetary strings and owner-accepted commercial evidence, excluding private review evidence",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PartnerFeePeriod"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  }
                },
                "required": [
                  "next"
                ]
              }
            },
            "required": [
              "data",
              "pagination"
            ]
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "readPartnerBillingAccount",
  "description": "Current active owner/admin/billing members read billing contact review history and safe account status. Private platform evidence and Stripe account/customer identifiers are excluded. Owner membership epoch changes require a new review before billing creation.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Billing account and contact history",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "account": {
                "anyOf": [
                  {
                    "$ref": "#/components/schemas/PartnerBillingAccount"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PartnerBillingContact"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  }
                },
                "required": [
                  "next"
                ]
              }
            },
            "required": [
              "account",
              "data",
              "pagination"
            ]
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "requestPartnerBillingAccount",
  "description": "Organization owner only; verified live provider identity and TOTP challenge within 10 minutes. Explicit consent uses the verified owner email and reviewed organization name; caller-provided email/name/customer IDs are rejected. UUID exact retry recovers the same request. One pending request per organization, seven-day expiry and ten new requests per UTC rolling day. Platform manual approval rechecks current owner epoch/email and the current CarSoft Stripe account. Approval creates no invoice, payment, app access or customer; customer provisioning is separate and release gated. No Connect or payout/distribution operations. Invoice workers and durable overdue notification queuing are locally verified. Automatic monthly cadence and signed Stripe event reconciliation are locally verified; actual Stripe sandbox acceptance and production release remain unfinished.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            },
            "consent": {
              "const": true
            }
          },
          "required": [
            "organizationId",
            "requestId",
            "consent"
          ],
          "additionalProperties": false
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Exact receipt retry",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object"
              }
            },
            "required": [
              "data"
            ]
          }
        }
      }
    },
    "201": {
      "description": "New contact consent",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "fingerprint": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$"
                  },
                  "status": {
                    "enum": [
                      "pending",
                      "approved",
                      "rejected",
                      "expired"
                    ]
                  },
                  "created": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "id",
                  "fingerprint",
                  "status",
                  "created"
                ]
              }
            },
            "required": [
              "data"
            ]
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}

{
  "operationId": "listPartnerFeeInvoices",
  "description": "Active owner/admin/billing membership and verified TOTP identity required. Read-only safe CarSoft invoice history; exact monetary strings and last confirmed provider status. Private review evidence and Stripe invoice/customer/account identifiers are excluded. Provider amounts are historical when state is review_required; do not treat status alone as a fresh payment proof. Paid records require verified Stripe payment allocations. Overdue notices require an explicit platform admin decision and never automatically suspend access. Partners collect their own fees; CarSoft issues its own agreed fees through its existing account. Hosted invoice URL validation is pinned to HTTPS invoice.stripe.com. Actual provider sandbox acceptance and production activation remain outstanding.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "parameters": [
    {
      "in": "query",
      "name": "organizationId",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "after",
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 25
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Read-only invoice records, excluding private identifiers",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "data": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PartnerFeeInvoice"
                }
              },
              "pagination": {
                "type": "object",
                "properties": {
                  "next": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid"
                  }
                },
                "required": [
                  "next"
                ]
              }
            },
            "required": [
              "data",
              "pagination"
            ]
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}