One platform, every department, powered by AI.

My accountMy account
carsoft.ai

Partner API reference.

0.8.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. Exact redirect/webhook/embedded hostnames require platform-reviewed DNS TXT ownership proofs, valid for 30 days; expiry or withdrawal denies live access and reproof requires fresh authorization. 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; separate provider/MFA-authenticated developer memberships and immutable update submissions are included; hosted signup/recovery/team invitation self-service, sandbox and hosted-provider lifecycle acceptance remain unfinished. Developer credential management and custody-aware offboarding are included. Large queued jobs, 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.

{
  "developerIdentity": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT",
    "description": "Configured identity provider JWT; verified issuer/signature/live user, confirmed email, TOTP aal2 and current organization membership required. Recent MFA required for mutations. Not the partner app OAuth token."
  },
  "partnerToken": {
    "type": "oauth2",
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "https://app.carsoft.ai/partners/authorize",
        "tokenUrl": "https://app.carsoft.ai/api/partners/oauth/token",
        "scopes": {
          "inventory:read": "inventory:read",
          "inventory:create": "inventory:create",
          "inventory:update": "inventory:update",
          "inventory:bulk": "inventory:bulk",
          "leads:read": "leads:read",
          "leads:create": "leads:create",
          "leads:update": "leads:update",
          "leads:bulk": "leads:bulk",
          "clients:read": "clients:read",
          "clients:create": "clients:create",
          "clients:update": "clients:update",
          "clients:bulk": "clients:bulk",
          "service:read": "service:read",
          "service:create": "service:create",
          "service:update": "service:update",
          "service:bulk": "service:bulk",
          "parts:read": "parts:read",
          "parts:create": "parts:create",
          "parts:update": "parts:update",
          "parts:bulk": "parts:bulk",
          "appointments:read": "appointments:read",
          "appointments:create": "appointments:create",
          "appointments:update": "appointments:update",
          "appointments:bulk": "appointments:bulk",
          "invoices:read": "invoices:read",
          "invoices:create": "invoices:create",
          "invoices:draft-update": "invoices:draft-update",
          "payments:links": "payments:links",
          "payments:read": "payments:read",
          "payments:charge": "payments:charge",
          "payments:refund": "payments:refund",
          "events:subscribe": "events:subscribe",
          "exports:create": "exports:create",
          "media:read": "media:read"
        }
      }
    }
  }
}

Endpoints 35

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"
            ]
          }
        }
      }
    }
  }
}
GET/api/partners/developer/me
GET · Operation details

Separate provider-authenticated identity with verified email and TOTP MFA. Lists up to 100 active memberships for this identity. Dealership cookies and partner app OAuth tokens are rejected. No platform/dealership authority is granted.

Declared responses: 200, default

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

Organization-scoped apps and latest approved manifest only. Excludes platform review evidence, dealership data and credentials. Active owner/admin/developer/support membership required.

Declared responses: 200, default

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

Immutable proposed app changes and shared decisions for one organization. Excludes private platform review evidence. Active owner/admin/developer/support membership required.

Declared responses: 200, default

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

Recent TOTP confirmation (within ten minutes) and active owner/admin/developer membership required. Records the exact manifest for manual review; creates no executable revision or dealership grant. UUID requestId is an original-result retry receipt. Changes to pricing/access/data use need a new submission. Base revision must be current.

Declared responses: 201, default

Full operation contract
{
  "operationId": "submitDeveloperUpdate",
  "description": "Recent TOTP confirmation (within ten minutes) and active owner/admin/developer membership required. Records the exact manifest for manual review; creates no executable revision or dealership grant. UUID requestId is an original-result retry receipt. Changes to pricing/access/data use need a new submission. Base revision must be current.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "organizationId": {
              "type": "string",
              "format": "uuid"
            },
            "appId": {
              "type": "string",
              "format": "uuid"
            },
            "baseRevisionId": {
              "type": "string",
              "format": "uuid"
            },
            "requestId": {
              "type": "string",
              "format": "uuid"
            },
            "sourceReference": {
              "type": "string",
              "minLength": 1,
              "maxLength": 1000
            },
            "manifest": {
              "type": "object",
              "description": "Exact proposed description, data_use, retention_days/exceptions, pricing, platform_charges, scopes, field_policy, embedded_origin, locations, redirects and webhook_origins. Unknown fields and platform review_evidence are rejected. At most 64 KiB, inside the request body limit."
            }
          },
          "required": [
            "organizationId",
            "appId",
            "baseRevisionId",
            "requestId",
            "sourceReference",
            "manifest"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPATCH/api/partners/developer/members
GET · Operation details

Active organization membership required. Returns developer member identifiers, roles/status/epochs; never dealership staff or secrets.

Declared responses: 200, default

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

Recent MFA and current owner/admin membership required. Expected epoch prevents stale overwrites. Admins cannot manage peer admins or owners; owner changes remain platform-reviewed. Revocation immediately denies developer API access. Membership revocation or role change retires clients whose current secret was issued to that member, plus untracked platform-issued clients when a technical member changes access. Other known holders are preserved. Reissue credentials and obtain fresh dealer OAuth after revocation.

Declared responses: 200, default

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

One-use, seven-day platform-reviewed invitation bound to the provider-verified email. Requires recent TOTP MFA. Replay, expiry, revocation, wrong email and existing membership are rejected. Acceptance grants only organization membership; no automatic app approval or dealership credentials.

Declared responses: 201, default

Full operation contract
{
  "operationId": "acceptDeveloperInvitation",
  "description": "One-use, seven-day platform-reviewed invitation bound to the provider-verified email. Requires recent TOTP MFA. Replay, expiry, revocation, wrong email and existing membership are rejected. Acceptance grants only organization membership; no automatic app approval or dealership credentials.",
  "security": [
    {
      "developerIdentity": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "invitation": {
              "type": "string",
              "pattern": "^csdi_[A-Za-z0-9_-]{43}$"
            }
          },
          "required": [
            "invitation"
          ]
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Developer API result; documented projections and pagination.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "default": {
      "description": "Structured error without private records or traces.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  },
                  "requestId": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "required": [
                  "code",
                  "message",
                  "requestId"
                ]
              }
            },
            "required": [
              "error"
            ]
          }
        }
      }
    }
  }
}
GETPOSTPATCH/api/partners/developer/credentials
GET · Operation details

Owner/admin/developer can read organization-scoped client metadata and versioned redirects/status. Secret values/hashes and current-secret custody records are excluded.

Declared responses: 200, default

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

Owner/admin and recent TOTP MFA required. App/revision/redirects must be approved and domains currently verified. At most 20 active clients per app. Creates a hashed backend secret and records the current recipient for offboarding; plaintext appears only in this response. This never authorizes a dealership. A UUID requestId provides deterministic original-client recovery after a lost response. An exact retry returns only that client metadata with secretUnavailable, never plaintext; revoke and deliberately replace it if the original secret was lost.

Declared responses: 200, 201, default

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

Owner/admin and recent TOTP MFA required. Expected credentialVersion prevents concurrent overwrite. Rotation invalidates old secrets/codes/families and transfers current-secret custody; requires active app/domain proof. Revocation is permanent and remains possible for a suspended app. Lists never recover plaintext secrets. A lost mutation response requires rereading metadata and deliberately reconciling/replacing credentials, never blind replay.

Declared responses: 200, default

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