One platform, every department, powered by AI.

My accountMy account
carsoft.ai

Partner API reference.

0.5.0-draft · Explore endpoints, authentication and schemas.

Download contractAll versions
Readiness and contract scope

Local implementation under verification; not deployed

Local implementation under verification. Production not activated/deployed. This draft covers implemented resource, intake, token, payment-intent and event-subscription routes. Resource/OAuth behavior has local HTTP tests; financial adapters have not completed processor sandbox acceptance. Customer invoice, unsubmitted payment cancellation and subscription-management contracts are included. Approved app updates require dealership re-consent; rotating or revoking a client immediately invalidates its old OAuth sessions. Bounded synchronous export/bulk jobs and authenticated marketing-gallery reads are included; large queued jobs, developer lifecycle, billing and complete financial adjustment/dispute interfaces remain incomplete.

This is an archived contract snapshot. Refer to the current version for active service details.

Authentication contracts

Use the authentication declared for each operation. Developer identity and partner app OAuth grant different access.

{
  "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"
        }
      }
    }
  }
}

Endpoints 29

GETPOST/api/partners/v1/inventory
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/inventory/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/leads
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/leads/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/clients
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/clients/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/service
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/service/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/parts
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/parts/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/appointments
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/appointments/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/applications
POST · Operation details

Exact allowed Origin and Turnstile action partner_application required. Submission grants no system access.

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/oauth/token
POST · Operation details

Code with S256 PKCE or rotating refresh token. Confidential clients authenticate. Client credentials/password grants unavailable.

Declared responses: 200, 400, 401, 503

Full operation contract
{
  "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"
    }
  }
}
POST/api/partners/v1/payments/links
POST · Operation details

Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.

Declared responses: 201, 202, default

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

Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.

Declared responses: 201, 202, default

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

Reviewed processor and verified merchant connection required. USD is the only current currency. Stable intent; unknown outcomes cannot be resubmitted as new payments. Refund approval applies to one exact amount for 15 minutes. Sandbox adapter acceptance remains pending.

Declared responses: 201, 202, default

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

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/v1/payments/{id}/cancel
POST · Operation details

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.

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/events/subscriptions
GET · Operation details

Declared responses: 200, default

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

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.

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPOST/api/partners/v1/invoices
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

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.

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/invoices/{id}
GET · Operation details

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

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.

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/events/subscriptions/{id}
GET · Operation details

Latest100 delivery summaries for this installation subscription; no payload snapshots.

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/v1/exports
POST · Operation details

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.

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
POST/api/partners/v1/bulk
POST · Operation details

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.

Declared responses: 201, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/v1/jobs/{id}
GET · Operation details

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.

Declared responses: 200, default

Full operation contract
{
  "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 · Operation details

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.

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GET/api/partners/v1/jobs/{id}/download
GET · Operation details

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.

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GET/api/partners/v1/inventory/{id}/photos
GET · Operation details

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.

Declared responses: 200, default

Full operation contract
{
  "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"
            ]
          }
        }
      }
    }
  }
}
GET/api/partners/v1/inventory/{id}/photos/{photoId}/download
GET · Operation details

Private no-store JPEG attachment from the exact tenant/vehicle/photo reference. Permissions and reference are checked again after provider read/re-encoding. Provider redirects are rejected, input bounded to 3 MiB/40 million pixels, supported JPEG/PNG/WebP re-encoded to at most 1600px with metadata stripped. Provider deadline 10 seconds; image processing budget 5 seconds excluding thread wait; at most four concurrent downloads per runtime instance. These technical safeguards cannot determine whether a dealership placed sensitive content in its marketing gallery; approved use and review obligations still apply. Upload/replacement/deletion and other attachment classes are unfinished/excluded.

Declared responses: 200, default

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