{ "openapi": "3.1.0", "info": { "title": "CarSoft Partner API", "version": "1.0.0", "description": "Released CarSoft partner API contract. Covers manually reviewed applications, scoped OAuth and operational resources, dealership installation/consent/revocation, bounded exports/bulk, protected gallery media, scoped events and isolated embeds. Developer account activation requires an approved application and published approved app, or a valid invitation to an eligible organization. Developer identities require verified email, TOTP and current organization membership. Partners collect their own fees; CarSoft bills partners through its existing Stripe account. Overdue invoices notify the platform administrator for a manual decision. Cancellation ends app/API access under the accepted agreement and preserves invoices already owed. Partner payment requests remain unavailable unless the separate reviewed processor/method/merchant/customer-consent and tracking gates are enabled. The public API never grants platform administration, dealership deletion, secrets or raw payment data. Documentation does not grant access or include sandbox credentials." }, "servers": [ { "url": "https://app.carsoft.ai", "description": "Production API host" } ], "paths": { "/api/partners/v1/inventory": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/inventory/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/leads": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/leads/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/clients": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/clients/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/service": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/service/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/parts": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/parts/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/appointments": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/appointments/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/applications": { "post": { "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" ] } } } } } } }, "/api/partners/oauth/token": { "post": { "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" } } } }, "/api/partners/v1/payments/links": { "post": { "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. These payment operations are disabled in the current production release and require separate platform activation.", "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" ] } } } } } } }, "/api/partners/v1/payments/charges": { "post": { "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. These payment operations are disabled in the current production release and require separate platform activation.", "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" ] } } } } } } }, "/api/partners/v1/payments/refunds": { "post": { "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. These payment operations are disabled in the current production release and require separate platform activation.", "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" ] } } } } } } }, "/api/partners/v1/payments/authorizations": { "get": { "operationId": "listSavedPaymentAuthorizations", "description": "payments:charge plus current actor payment authority required. Lists only active, unexpired customer authorizations for this installation and its exact consent version, active verified merchant and approved processor/method. The opaque id is savedMethodId for a charge. No provider IDs, card/bank details, customer names, invitation tokens or secrets are returned. Re-consent requires fresh customer authorization. This does not itself authorize a charge or guarantee its remaining financial quota.", "security": [ { "partnerToken": [ "payments:charge" ] } ], "parameters": [ { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "App-bound opaque customer authorization references", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "clientId": { "type": "string" }, "processorId": { "type": "string" }, "maximumChargeMinor": { "type": "integer", "minimum": 1, "maximum": 99999999 }, "currency": { "const": "usd" }, "methodType": { "enum": [ "card", "us_bank_account" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "clientId", "processorId", "maximumChargeMinor", "currency", "methodType", "expiresAt" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "nextAfter": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "nextAfter" ] } }, "required": [ "data", "meta" ] } } } }, "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" ] } } } } } } }, "/api/partners/v1/payments/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "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" ] } } } } } } }, "/api/partners/v1/payments/{id}/cancel": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "post": { "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" ] } } } } } } }, "/api/partners/events/subscriptions": { "get": { "operationId": "listSubscriptions", "security": [ { "partnerToken": [ "events:subscribe" ] } ], "responses": { "200": { "description": "Current installation subscriptions.", "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/invoices": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/v1/invoices/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/events/subscriptions/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/exports": { "post": { "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" ] } } } } } } }, "/api/partners/v1/bulk": { "post": { "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" ] } } } } } } }, "/api/partners/v1/jobs/{id}": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/v1/jobs/{id}/download": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "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" ] } } } } } } }, "/api/partners/v1/inventory/{id}/photos": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "get": { "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" ] } } } } } } }, "/api/partners/v1/inventory/{id}/photos/{photoId}/download": { "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, { "in": "path", "name": "photoId", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } } ], "get": { "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 unavailable.", "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" ] } } } } } } }, "/api/partners/developer/me": { "get": { "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" ] } } } } } } }, "/api/partners/developer/apps": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/developer/submissions": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } } }, "/api/partners/developer/members": { "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/developer/domains": { "get": { "operationId": "listDeveloperDomains", "description": "Current owner/admin/developer membership. Paginated organization-owned domain metadata with database-clock verification status; no challenge hash, secret value or private review evidence. Application-owned intake proofs remain platform administered.", "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" ] } } } } } }, "post": { "operationId": "challengeDeveloperDomain", "description": "Current owner/admin and recent TOTP MFA. Create or rotate a one-hour exact-hostname TXT challenge; the random TXT value is returned once. At most 100 domain records per organization. A new challenge replaces any earlier unfinished challenge; retry by creating a fresh challenge if its response is lost. Current verified ownership remains valid until expiry or withdrawal. Verification lasts 30 days and never approves an application or grants dealership authority.", "security": [ { "developerIdentity": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "hostname": { "type": "string", "maxLength": 230, "description": "Exact public hostname, without URL, port or trailing dot." } }, "required": [ "organizationId", "hostname" ], "additionalProperties": false } } } }, "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" ] } } } } } }, "patch": { "operationId": "decideDeveloperDomain", "description": "Current owner/admin and recent TOTP MFA. Verify the exact current challenge with bounded server-side DNS, or withdraw the current proof with a reason. Organization ownership and challenge version are rechecked inside the security-coordinated transaction after DNS. Old/expired or foreign proofs cannot complete. Withdrawal invalidates affected credentials; proving the domain again cannot revive old tokens.", "security": [ { "developerIdentity": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "organizationId": { "type": "string", "format": "uuid" }, "proofId": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "decision": { "enum": [ "verify", "revoke" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "Required for revoke." } }, "required": [ "organizationId", "proofId", "version", "decision" ], "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" ] } } } } } } }, "/api/partners/developer/invitations": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/developer/invitations/accept": { "post": { "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" ] } } } } } } }, "/api/partners/developer/credentials": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/developer/sharing": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/developer/ownership": { "get": { "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" ] } } } } } }, "post": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/developer/billing/agreements": { "get": { "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" ] } } } } } }, "patch": { "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" ] } } } } } } }, "/api/partners/developer/billing/cancellation": { "get": { "operationId": "readPartnerCancellation", "description": "Verified TOTP and owner/admin/billing membership required. Billing reads and organization discovery remain available after cancellation while the member remains active. Private reasons, member IDs and epochs are excluded.", "security": [ { "developerIdentity": [] } ], "parameters": [ { "in": "query", "name": "organizationId", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Immutable accepted cancellation; GET returns null when none exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/PartnerCancellation" }, { "type": "null" } ] } }, "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" ] } } } } } }, "post": { "operationId": "cancelPartnerAgreement", "description": "Current organization owner with recent TOTP MFA confirms cancel against the current accepted agreement and exact fingerprint. One immutable cancellation per organization; reuse requestId and identical reason/agreement on retry. Period-end access ends at the next UTC month boundary. Immediate-prorated access ends when the request is accepted; the current UTC day counts for final daily fees. Database-clock guards stop API requests, authorization grants, installs, event delivery and processor submissions at the cutoff. Delayed cleanup never extends the original 30-day deletion deadline. Final monthly fees stop at the commercial cutoff; owed invoices remain payable. Overdue invoices remain separate manual decisions. Future pricing cannot extend a cancellation. No payment or refund is created by this request. Reinstatement requires platform review and is not available through cancellation retries.", "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}$" }, "requestId": { "type": "string", "format": "uuid" }, "reason": { "type": "string", "minLength": 1, "maxLength": 4000 }, "confirmation": { "const": "cancel" } }, "required": [ "organizationId", "agreementId", "fingerprint", "requestId", "reason", "confirmation" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Immutable accepted cancellation; GET returns null when none exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#/components/schemas/PartnerCancellation" }, { "type": "null" } ] } }, "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" ] } } } } } } }, "/api/partners/developer/billing/periods": { "get": { "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. Automatic monthly scheduling, invoice issuance/reconciliation and signed provider events process reviewed billing accounts and accepted agreements. Durable overdue notices await a platform administrator decision. Voluntary cancellation enforces the accepted cutoff and final proration. Exceptional fee adjustment automation is disabled in this release.", "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" ] } } } } } } }, "/api/partners/developer/billing/account": { "get": { "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" ] } } } } } }, "post": { "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. Automatic monthly billing and signed provider event reconciliation operate only after accepted pricing and platform billing-account review. Overdue notices await a platform administrator decision.", "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" ] } } } } } } }, "/api/partners/developer/billing/invoices": { "get": { "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.", "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" ] } } } } } } }, "/api/partners/catalog": { "get": { "operationId": "listPublicCatalog", "description": "Anonymous public projection of published approved apps with an approved revision and active eligible organization. At most 50 candidates per page; eligibility filtering can yield an empty page with a non-null cursor. Follow nextCursor until null. Only after is accepted, once, as a UUID. No private review, organization identifiers, credentials or dealership data. Responses are not cached; 120 requests per IP per minute.", "security": [], "parameters": [ { "in": "query", "name": "after", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Public app listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "apps": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/PublicCatalogApp" } }, "nextCursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "apps", "nextCursor" ], "additionalProperties": false } } } }, "400": { "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" ] } } } }, "429": { "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" ] } } }, "headers": { "Retry-After": { "schema": { "type": "integer", "const": 60 } } } }, "503": { "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" ] } } } }, "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" ] } } } } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "requestId": { "type": "string", "format": "uuid" } }, "required": [] } }, "required": [] }, "inventoryRecord": { "type": "object", "properties": { "id": { "type": "string" }, "partner_revision": { "type": "integer", "minimum": 1 }, "stock": { "type": "string", "maxLength": 40 }, "vehicle": { "type": "string", "maxLength": 200 }, "year": { "type": "string", "maxLength": 4 }, "make": { "type": "string", "maxLength": 80 }, "model": { "type": "string", "maxLength": 80 }, "body": { "type": "string", "maxLength": 80 }, "trim": { "type": "string", "maxLength": 100 }, "color": { "type": "string", "maxLength": 80 }, "condition": { "type": "string", "maxLength": 200, "enum": [ "New", "Used", "Certified" ] }, "price": { "type": "string", "maxLength": 40 }, "miles": { "type": "string", "maxLength": 40 }, "vin": { "type": "string", "maxLength": 17 }, "status": { "type": "string", "maxLength": 200, "enum": [ "Available", "Hold", "Recon", "Sold" ] }, "arrived": { "type": "string", "maxLength": 40 }, "public_description": { "type": "string", "maxLength": 5000 } }, "required": [ "id", "partner_revision" ], "additionalProperties": false, "description": "Only approved fields are returned." }, "inventoryCreate": { "type": "object", "properties": { "year": { "type": "string", "maxLength": 4 }, "make": { "type": "string", "maxLength": 80 }, "model": { "type": "string", "maxLength": 80 }, "body": { "type": "string", "maxLength": 80 }, "trim": { "type": "string", "maxLength": 100 }, "color": { "type": "string", "maxLength": 80 }, "condition": { "type": "string", "maxLength": 200, "enum": [ "New", "Used", "Certified" ] }, "price": { "type": "string", "maxLength": 40 }, "miles": { "type": "string", "maxLength": 40 }, "vin": { "type": "string", "maxLength": 17 }, "status": { "type": "string", "maxLength": 200, "enum": [ "Available", "Hold", "Recon", "Sold" ] }, "arrived": { "type": "string", "maxLength": 40 }, "public_description": { "type": "string", "maxLength": 5000 } }, "required": [ "year", "make", "model", "body", "color" ], "additionalProperties": false }, "inventoryUpdate": { "type": "object", "properties": { "year": { "type": "string", "maxLength": 4 }, "make": { "type": "string", "maxLength": 80 }, "model": { "type": "string", "maxLength": 80 }, "body": { "type": "string", "maxLength": 80 }, "trim": { "type": "string", "maxLength": 100 }, "color": { "type": "string", "maxLength": 80 }, "condition": { "type": "string", "maxLength": 200, "enum": [ "New", "Used", "Certified" ] }, "price": { "type": "string", "maxLength": 40 }, "miles": { "type": "string", "maxLength": 40 }, "vin": { "type": "string", "maxLength": 17 }, "status": { "type": "string", "maxLength": 200, "enum": [ "Available", "Hold", "Recon", "Sold" ] }, "arrived": { "type": "string", "maxLength": 40 }, "public_description": { "type": "string", "maxLength": 5000 } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "leadsRecord": { "type": "object", "properties": { "id": { "type": "string" }, "partner_revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 254 }, "address": { "type": "string", "maxLength": 500 }, "source": { "type": "string", "maxLength": 200 }, "stock": { "type": "string", "maxLength": 40 }, "vehicle_id": { "type": [ "string", "null" ], "maxLength": 128 }, "interest": { "type": "string", "maxLength": 200 }, "condition": { "type": "string", "maxLength": 40 }, "status": { "type": "string", "maxLength": 200, "enum": [ "New", "Contacted", "Appointment", "Showroom", "Lost" ] }, "created": { "type": "string", "maxLength": 40 } }, "required": [ "id", "partner_revision" ], "additionalProperties": false, "description": "Only approved fields are returned." }, "leadsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 254 }, "address": { "type": "string", "maxLength": 500 }, "source": { "type": "string", "maxLength": 200 }, "stock": { "type": "string", "maxLength": 40 }, "vehicle_id": { "type": [ "string", "null" ], "maxLength": 128 }, "interest": { "type": "string", "maxLength": 200 }, "condition": { "type": "string", "maxLength": 40 }, "status": { "type": "string", "maxLength": 200, "enum": [ "New", "Contacted", "Appointment", "Showroom", "Lost" ] } }, "required": [ "name" ], "additionalProperties": false }, "leadsUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 254 }, "address": { "type": "string", "maxLength": 500 }, "source": { "type": "string", "maxLength": 200 }, "stock": { "type": "string", "maxLength": 40 }, "vehicle_id": { "type": [ "string", "null" ], "maxLength": 128 }, "interest": { "type": "string", "maxLength": 200 }, "condition": { "type": "string", "maxLength": 40 }, "status": { "type": "string", "maxLength": 200, "enum": [ "New", "Contacted", "Appointment", "Showroom", "Lost" ] } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "clientsRecord": { "type": "object", "properties": { "id": { "type": "string" }, "partner_revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 254 }, "address": { "type": "string", "maxLength": 500 }, "vehicle": { "type": "string", "maxLength": 200 }, "stock": { "type": "string", "maxLength": 40 }, "source": { "type": "string", "maxLength": 200 }, "since": { "type": "string", "maxLength": 40 } }, "required": [ "id", "partner_revision" ], "additionalProperties": false, "description": "Only approved fields are returned." }, "clientsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 254 }, "address": { "type": "string", "maxLength": 500 }, "vehicle": { "type": "string", "maxLength": 200 }, "stock": { "type": "string", "maxLength": 40 }, "source": { "type": "string", "maxLength": 200 } }, "required": [ "name" ], "additionalProperties": false }, "clientsUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 254 }, "address": { "type": "string", "maxLength": 500 }, "vehicle": { "type": "string", "maxLength": 200 }, "stock": { "type": "string", "maxLength": 40 }, "source": { "type": "string", "maxLength": 200 } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "serviceRecord": { "type": "object", "properties": { "id": { "type": "string" }, "partner_revision": { "type": "integer", "minimum": 1 }, "ro": { "type": "string", "maxLength": 40 }, "customer": { "type": "string", "maxLength": 200 }, "vehicle": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "status": { "type": "string", "maxLength": 40 }, "promise": { "type": "string", "maxLength": 200 }, "price": { "type": "string", "maxLength": 40 }, "opened": { "type": "string", "maxLength": 40 }, "miles": { "type": "string", "maxLength": 40 } }, "required": [ "id", "partner_revision" ], "additionalProperties": false, "description": "Only approved fields are returned." }, "serviceCreate": { "type": "object", "properties": { "ro": { "type": "string", "maxLength": 40 }, "customer": { "type": "string", "maxLength": 200 }, "vehicle": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "status": { "type": "string", "maxLength": 40, "enum": [ "Scheduled", "In shop", "Waiting parts", "Ready" ] }, "promise": { "type": "string", "maxLength": 200 }, "price": { "type": "string", "maxLength": 40 }, "miles": { "type": "string", "maxLength": 40 } }, "required": [ "ro", "customer" ], "additionalProperties": false }, "serviceUpdate": { "type": "object", "properties": { "ro": { "type": "string", "maxLength": 40 }, "customer": { "type": "string", "maxLength": 200 }, "vehicle": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "status": { "type": "string", "maxLength": 40, "enum": [ "Scheduled", "In shop", "Waiting parts", "Ready" ] }, "promise": { "type": "string", "maxLength": 200 }, "price": { "type": "string", "maxLength": 40 }, "miles": { "type": "string", "maxLength": 40 } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "partsRecord": { "type": "object", "properties": { "id": { "type": "string" }, "partner_revision": { "type": "integer", "minimum": 1 }, "name": { "type": "string", "maxLength": 200 }, "sku": { "type": "string", "maxLength": 80 }, "category": { "type": "string", "maxLength": 80 }, "qty": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "reorder_at": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "unit": { "type": "string", "maxLength": 40 }, "price": { "type": "string", "maxLength": 40 } }, "required": [ "id", "partner_revision" ], "additionalProperties": false, "description": "Only approved fields are returned." }, "partsCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "category": { "type": "string", "maxLength": 80 }, "qty": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "reorder_at": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "unit": { "type": "string", "maxLength": 40 }, "price": { "type": "string", "maxLength": 40 } }, "required": [ "name" ], "additionalProperties": false }, "partsUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "category": { "type": "string", "maxLength": 80 }, "qty": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "reorder_at": { "type": "integer", "minimum": 0, "maximum": 1000000000 }, "unit": { "type": "string", "maxLength": 40 }, "price": { "type": "string", "maxLength": 40 } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "appointmentsRecord": { "type": "object", "properties": { "id": { "type": "string" }, "partner_revision": { "type": "integer", "minimum": 1 }, "kind": { "type": "string", "maxLength": 200, "enum": [ "Test drive", "Delivery", "Booked by buyer", "Front desk", "Other" ] }, "day": { "type": "string", "maxLength": 10 }, "start_time": { "type": "string", "maxLength": 10 }, "customer": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "vehicle": { "type": "string", "maxLength": 200 } }, "required": [ "id", "partner_revision" ], "additionalProperties": false, "description": "Only approved fields are returned." }, "appointmentsCreate": { "type": "object", "properties": { "kind": { "type": "string", "maxLength": 200, "enum": [ "Test drive", "Delivery", "Booked by buyer", "Front desk", "Other" ] }, "day": { "type": "string", "maxLength": 10 }, "start_time": { "type": "string", "maxLength": 10 }, "customer": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "vehicle": { "type": "string", "maxLength": 200 } }, "required": [ "kind", "day", "customer" ], "additionalProperties": false }, "appointmentsUpdate": { "type": "object", "properties": { "kind": { "type": "string", "maxLength": 200, "enum": [ "Test drive", "Delivery", "Booked by buyer", "Front desk", "Other" ] }, "day": { "type": "string", "maxLength": 10 }, "start_time": { "type": "string", "maxLength": 10 }, "customer": { "type": "string", "maxLength": 200 }, "phone": { "type": "string", "maxLength": 40 }, "vehicle": { "type": "string", "maxLength": 200 } }, "required": [], "additionalProperties": false, "minProperties": 1 }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "invoiceId": { "type": "string" }, "processorId": { "type": "string" }, "operation": { "enum": [ "link", "charge", "refund" ] }, "amountMinor": { "type": "integer", "minimum": 1, "maximum": 99999999 }, "currency": { "const": "usd" }, "state": { "enum": [ "approval_required", "reserved", "submitting", "pending", "requires_action", "succeeded", "failed", "unknown", "canceled" ] }, "paymentUrl": { "type": [ "string", "null" ], "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [] }, "Invoice": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "department": { "enum": [ "Vehicles", "Service", "Parts" ] }, "customer": { "type": "string" }, "clientId": { "type": [ "string", "null" ] }, "currency": { "const": "usd" }, "draft": { "type": "boolean" }, "partner_revision": { "type": "integer", "minimum": 1 }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "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 } }, "totalMinor": { "type": "integer" }, "paidMinor": { "type": "integer" }, "refundedMinor": { "type": "integer" }, "voided": { "type": "boolean" } }, "required": [], "additionalProperties": false }, "PartnerCancellation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "agreementId": { "type": "string", "format": "uuid" }, "requestedAt": { "type": "string", "format": "date-time" }, "accessEndsAt": { "type": "string", "format": "date-time" }, "billingEndOn": { "type": "string", "format": "date" }, "policy": { "type": "string", "enum": [ "period_end", "immediate_prorated" ] } }, "required": [ "id", "agreementId", "requestedAt", "accessEndsAt", "billingEndOn", "policy" ], "additionalProperties": false }, "PartnerBillingUsage": { "type": "object", "properties": { "apiCalls": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "installationCount": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "installationDays": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "partnerRevenueMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "activeDays": { "type": "integer", "minimum": 0, "maximum": 31 }, "periodDays": { "type": "integer", "minimum": 28, "maximum": 31 }, "immediateCancellation": { "type": "boolean" } }, "required": [ "apiCalls", "installationCount", "installationDays", "partnerRevenueMinor", "activeDays", "periodDays", "immediateCancellation" ], "additionalProperties": false }, "PartnerBillingCalculation": { "type": "object", "properties": { "baseMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "apiMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "installationMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "revenueShareMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "spendingCreditMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "subtotalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "taxMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "totalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." } }, "required": [ "baseMinor", "apiMinor", "installationMinor", "revenueShareMinor", "spendingCreditMinor", "subtotalMinor", "taxMinor", "totalMinor" ], "additionalProperties": false }, "PartnerBillingTerms": { "type": "object", "properties": { "currency": { "type": "string", "pattern": "^[a-z]{3}$" }, "baseFeeMinor": { "type": "integer", "minimum": 0, "maximum": 99999999 }, "apiUnitPriceMinor": { "type": "integer", "minimum": 0, "maximum": 99999999 }, "apiUnitSize": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "installationFeeMinor": { "type": "integer", "minimum": 0, "maximum": 99999999 }, "revenueShareBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "spendLimitMinor": { "type": "integer", "minimum": 0, "maximum": 99999999 }, "dueDays": { "type": "integer", "minimum": 1, "maximum": 90 }, "proration": { "enum": [ "none", "daily" ] }, "cancellation": { "enum": [ "period_end", "immediate_prorated" ] }, "taxMode": { "enum": [ "none", "exclusive", "inclusive" ] }, "taxBps": { "type": "integer", "minimum": 0, "maximum": 10000 }, "pastDuePolicy": { "const": "manual" }, "graceDays": { "const": 0 }, "description": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "currency", "baseFeeMinor", "apiUnitPriceMinor", "apiUnitSize", "installationFeeMinor", "revenueShareBps", "spendLimitMinor", "dueDays", "proration", "cancellation", "taxMode", "taxBps", "pastDuePolicy", "graceDays", "description" ], "additionalProperties": false, "description": "Exact owner-accepted terms. The spending limit must cover the base fee; no-tax terms require zero tax; the spending limit plus exclusive tax must fit 99,999,999 minor units." }, "PartnerFeePeriod": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "agreement_id": { "type": "string", "format": "uuid" }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date", "description": "Exclusive first day of next UTC calendar month." }, "effective_from": { "type": "string", "format": "date" }, "terms": { "$ref": "#/components/schemas/PartnerBillingTerms" }, "usage": { "$ref": "#/components/schemas/PartnerBillingUsage" }, "calculation": { "$ref": "#/components/schemas/PartnerBillingCalculation" }, "revenue_report_id": { "type": [ "string", "null" ], "format": "uuid" }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "organization_id", "agreement_id", "period_start", "period_end", "effective_from", "terms", "usage", "calculation", "revenue_report_id", "fingerprint", "created_at" ], "additionalProperties": false }, "PartnerBillingContact": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "member_id": { "type": "string", "format": "uuid" }, "member_epoch": { "type": "integer", "minimum": 1 }, "user_id": { "type": "string", "format": "uuid" }, "verified_email": { "type": "string", "format": "email" }, "billing_name": { "type": "string" }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "enum": [ "pending", "approved", "rejected", "expired" ] }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "member_id", "member_epoch", "user_id", "verified_email", "billing_name", "fingerprint", "status", "created_at", "expires_at", "reviewed_at" ], "additionalProperties": false }, "PartnerBillingAccount": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "fingerprint": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "state": { "enum": [ "creating", "active", "review_required", "paused" ] }, "live_mode": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "request_id", "fingerprint", "state", "live_mode", "created_at", "activated_at" ], "additionalProperties": false }, "PartnerFeeInvoiceProvider": { "type": "object", "properties": { "status": { "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "totalMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "paidMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "remainingMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Exact integer minor units as a string; preserve precision." }, "hostedInvoiceUrl": { "type": [ "string", "null" ], "format": "uri", "description": "Validated HTTPS invoice.stripe.com URL only." }, "dueAt": { "type": [ "string", "null" ], "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time" }, "overdue": { "type": "boolean" }, "preCreditMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Verified credits against the original unpaid invoice; not cash received." }, "postCreditMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Verified post-payment credits; does not rewrite original cash received." }, "appliedBalanceMinor": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,30})$", "description": "Verified customer balance credits applied to this invoice, separately from actual cash paid. Private balance transaction proofs are excluded." } }, "required": [ "status", "totalMinor", "paidMinor", "remainingMinor", "hostedInvoiceUrl", "dueAt", "paidAt", "overdue" ], "additionalProperties": false }, "PartnerFeeInvoice": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "period_id": { "type": "string", "format": "uuid" }, "organization_id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "queued", "working", "tracking", "review_required", "closed" ] }, "period_start": { "type": "string", "format": "date" }, "period_end": { "type": "string", "format": "date" }, "currency": { "type": "string", "pattern": "^[a-z]{3}$" }, "calculation": { "$ref": "#/components/schemas/PartnerBillingCalculation" }, "provider": { "anyOf": [ { "$ref": "#/components/schemas/PartnerFeeInvoiceProvider" }, { "type": "null" } ] }, "provider_checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "period_id", "organization_id", "state", "period_start", "period_end", "currency", "calculation", "provider", "provider_checked_at", "created_at" ], "additionalProperties": false }, "PublicCatalogApp": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "provider": { "type": "string" }, "pricing": { "type": "string" }, "categories": { "type": "array", "uniqueItems": true, "items": { "enum": [ "inventory", "leads", "clients", "service", "parts", "appointments" ] } } }, "required": [ "id", "name", "description", "provider", "pricing", "categories" ], "additionalProperties": false } }, "securitySchemes": { "developerIdentity": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Configured identity provider JWT; verified issuer/signature/live user, confirmed email, TOTP aal2 and current organization membership required. Recent MFA required for mutations. Not the partner app OAuth token." }, "partnerToken": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://app.carsoft.ai/partners/authorize", "tokenUrl": "https://app.carsoft.ai/api/partners/oauth/token", "scopes": { "inventory:read": "inventory:read", "inventory:create": "inventory:create", "inventory:update": "inventory:update", "inventory:bulk": "inventory:bulk", "leads:read": "leads:read", "leads:create": "leads:create", "leads:update": "leads:update", "leads:bulk": "leads:bulk", "clients:read": "clients:read", "clients:create": "clients:create", "clients:update": "clients:update", "clients:bulk": "clients:bulk", "service:read": "service:read", "service:create": "service:create", "service:update": "service:update", "service:bulk": "service:bulk", "parts:read": "parts:read", "parts:create": "parts:create", "parts:update": "parts:update", "parts:bulk": "parts:bulk", "appointments:read": "appointments:read", "appointments:create": "appointments:create", "appointments:update": "appointments:update", "appointments:bulk": "appointments:bulk", "invoices:read": "invoices:read", "invoices:create": "invoices:create", "invoices:draft-update": "invoices:draft-update", "payments:links": "payments:links", "payments:read": "payments:read", "payments:charge": "payments:charge", "payments:refund": "payments:refund", "events:subscribe": "events:subscribe", "exports:create": "exports:create", "media:read": "media:read" } } } } } }, "x-carsoft-readiness": "Production release; partner access requires manual approval and dealership consent", "x-carsoft-embedding": { "status": "released-with-reviewed-permissions", "locations": [ "apps", "vehicle-tab", "customer-tab", "dashboard-widget", "record-action" ], "request": { "type": "object", "properties": { "type": { "const": "carsoft.context" }, "requestId": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,64}$" } }, "required": [ "type", "requestId" ] }, "context": { "type": "object", "properties": { "appId": { "type": "string", "format": "uuid" }, "installationId": { "type": "string", "format": "uuid" }, "locale": { "const": "en-US" }, "location": { "enum": [ "apps", "vehicle-tab", "customer-tab", "dashboard-widget", "record-action" ] }, "record": { "type": "object", "properties": { "resource": { "enum": [ "inventory", "clients" ] }, "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,128}$" } }, "required": [ "resource", "id" ] } }, "required": [ "appId", "installationId", "locale", "location" ] }, "recordPolicy": "Record tabs and actions require approved and installed resource:read plus current native viewer and dealership record access. Apps/widgets have no record context. Context IDs never grant API authority.", "transport": "Exact iframe origin and window identity; read-only current server authorization before each response. At most60 context checks per native viewer per minute; no concurrent frame requests and one request per second. Navigation, downloads, clipboard, popups and financial host commands are unavailable." }, "x-carsoft-prohibited": [ "record deletion", "staff information and management", "platform administration", "cross-dealership grants", "merchant/login secrets", "identity documents", "internal notes", "customer financial information" ] }