{
  "openapi": "3.1.0",
  "info": {
    "title": "LedgerHQ Agent API",
    "version": "0.1.0",
    "description": "Scoped API for agents that need access to a firm's LedgerHQ-connected accounting clients."
  },
  "servers": [
    {
      "url": "https://ledgerhq.app/api/agent/v1"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/status": {
      "get": {
        "summary": "Check API status",
        "operationId": "getAgentApiStatus",
        "responses": {
          "200": {
            "description": "API status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/StatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/qbo/clients": {
      "get": {
        "summary": "List accessible QBO clients",
        "operationId": "listQboClients",
        "responses": {
          "200": {
            "description": "Accessible clients",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Client"
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/qbo/coverage": {
      "get": {
        "summary": "List LedgerHQ QBO API coverage",
        "description": "Returns the registry of QBO entities exposed through LedgerHQ, including operations and scopes.",
        "operationId": "listQboCoverage",
        "responses": {
          "200": {
            "description": "QBO coverage registry",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/skills": {
      "get": {
        "summary": "List LedgerHQ agent skills",
        "operationId": "listAgentSkills",
        "responses": {
          "200": {
            "description": "Available skills",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object" } } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/skills/{skillId}": {
      "get": {
        "summary": "Get one LedgerHQ agent skill recipe",
        "operationId": "getAgentSkill",
        "parameters": [
          {
            "name": "skillId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "example": "create_invoice" }
          }
        ],
        "responses": {
          "200": {
            "description": "Skill recipe",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/recipes": {
      "get": {
        "summary": "Get full machine-readable QBO recipe bundle",
        "operationId": "getAgentRecipes",
        "responses": {
          "200": {
            "description": "Recipe bundle",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/query": {
      "post": {
        "summary": "Run a QBO query through LedgerHQ",
        "description": "Runs a QBO SQL-like query against the connected company.",
        "operationId": "runQboQuery",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string",
                    "example": "select * from Customer maxresults 25"
                  }
                },
                "required": ["query"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QBO query response",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/request": {
      "post": {
        "summary": "Call a relative QBO Accounting API path through LedgerHQ",
        "description": "Pass-through endpoint for QBO Accounting API paths relative to /v3/company/{realmId}.",
        "operationId": "requestQboApi",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "method": {
                    "type": "string",
                    "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"],
                    "default": "GET"
                  },
                  "path": {
                    "type": "string",
                    "example": "reports/ProfitAndLoss"
                  },
                  "query": {
                    "type": "object"
                  },
                  "body": {
                    "type": "object"
                  }
                },
                "required": ["path"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QBO API response",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/entities/{entity}": {
      "get": {
        "summary": "List QBO entities through the generic gateway",
        "operationId": "listQboEntities",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" },
          { "$ref": "#/components/parameters/EntityName" },
          {
            "name": "maxResults",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }
          },
          {
            "name": "startPosition",
            "in": "query",
            "schema": { "type": "integer", "minimum": 1, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "QBO entity list",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a QBO entity through the generic gateway",
        "operationId": "createQboEntity",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" },
          { "$ref": "#/components/parameters/EntityName" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "QBO entity created",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/entities/{entity}/{id}": {
      "get": {
        "summary": "Get one QBO entity through the generic gateway",
        "operationId": "getQboEntity",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" },
          { "$ref": "#/components/parameters/EntityName" },
          { "$ref": "#/components/parameters/EntityRecordId" }
        ],
        "responses": {
          "200": {
            "description": "QBO entity",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update one QBO entity through the generic gateway",
        "operationId": "updateQboEntity",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" },
          { "$ref": "#/components/parameters/EntityName" },
          { "$ref": "#/components/parameters/EntityRecordId" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "type": "object" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QBO entity updated",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete one QBO entity through the generic gateway",
        "description": "Requires SyncToken in the JSON body or query string.",
        "operationId": "deleteQboEntity",
        "parameters": [
          { "$ref": "#/components/parameters/ClientId" },
          { "$ref": "#/components/parameters/EntityName" },
          { "$ref": "#/components/parameters/EntityRecordId" }
        ],
        "responses": {
          "200": {
            "description": "QBO entity deleted",
            "content": {
              "application/json": {
                "schema": { "type": "object", "properties": { "data": { "type": "object" } }, "required": ["data"] }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/transactions": {
      "get": {
        "summary": "List QBO transactions by type",
        "description": "Lists allowlisted QBO transaction objects. Requires qbo:transactions:read.",
        "operationId": "listQboTransactions",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          },
          {
            "$ref": "#/components/parameters/TransactionEntityType"
          },
          {
            "name": "maxResults",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000,
              "default": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "QBO transaction list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a QBO transaction through LedgerHQ",
        "description": "Creates an allowlisted QBO transaction object. Requires qbo:transactions:create.",
        "operationId": "createQboTransaction",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionWriteRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "QBO write completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionWriteResponse"
                }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/transactions/{transactionId}": {
      "get": {
        "summary": "Get one QBO transaction by type and id",
        "description": "Fetches one allowlisted QBO transaction object. Requires qbo:transactions:read.",
        "operationId": "getQboTransaction",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          },
          {
            "$ref": "#/components/parameters/TransactionId"
          },
          {
            "$ref": "#/components/parameters/TransactionEntityType"
          }
        ],
        "responses": {
          "200": {
            "description": "QBO transaction",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      },
      "patch": {
        "summary": "Update a QBO transaction through LedgerHQ",
        "description": "Updates an allowlisted QBO transaction object. Requires qbo:transactions:update.",
        "operationId": "updateQboTransaction",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          },
          {
            "$ref": "#/components/parameters/TransactionId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransactionWriteRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "QBO write completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionWriteResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a QBO transaction through LedgerHQ",
        "description": "Deletes an allowlisted QBO transaction object. Requires qbo:transactions:delete and the QBO SyncToken.",
        "operationId": "deleteQboTransaction",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          },
          {
            "$ref": "#/components/parameters/TransactionId"
          }
        ],
        "responses": {
          "200": {
            "description": "QBO delete completed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionWriteResponse"
                }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}": {
      "get": {
        "summary": "Get one QBO client",
        "operationId": "getQboClient",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          }
        ],
        "responses": {
          "200": {
            "description": "Client",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Client"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/reports/{reportName}": {
      "get": {
        "summary": "Fetch a QBO report",
        "operationId": "getQboReport",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          },
          {
            "name": "reportName",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["profit-loss", "balance-sheet", "trial-balance", "general-ledger"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "QBO report payload",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/qbo/clients/{clientId}/{entity}": {
      "get": {
        "summary": "Fetch QBO entity list",
        "operationId": "getQboEntityList",
        "parameters": [
          {
            "$ref": "#/components/parameters/ClientId"
          },
          {
            "name": "entity",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["chart-accounts", "vendors", "customers"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Entity list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/skills/client-health-scan": {
      "get": {
        "summary": "Run read-only client health scan",
        "operationId": "runClientHealthScan",
        "responses": {
          "200": {
            "description": "Scan result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    },
    "/audit-events": {
      "get": {
        "summary": "List audit events visible to the agent",
        "operationId": "listAuditEvents",
        "responses": {
          "200": {
            "description": "Audit events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "parameters": {
      "ClientId": {
        "name": "clientId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "qbo-411909201"
        }
      },
      "TransactionId": {
        "name": "transactionId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "TransactionEntityType": {
        "name": "entityType",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string",
          "enum": ["bill", "bill-payment", "credit-memo", "deposit", "estimate", "invoice", "journal-entry", "payment", "purchase", "refund-receipt", "sales-receipt", "transfer", "vendor-credit"],
          "default": "purchase"
        }
      },
      "EntityName": {
        "name": "entity",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "example": "invoice"
        }
      },
      "EntityRecordId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "StatusResponse": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "service": {
            "type": "string"
          },
          "capabilities": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": ["ok", "service"]
      },
      "Client": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "qboCompanyId": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "lastSyncAt": {
            "type": "string"
          },
          "agentAccess": {
            "type": "string"
          }
        },
        "required": ["id", "name", "qboCompanyId", "status"]
      },
      "TransactionWriteRequest": {
        "type": "object",
        "properties": {
          "entityType": {
            "type": "string",
            "enum": ["bill", "bill-payment", "credit-memo", "deposit", "estimate", "invoice", "journal-entry", "payment", "purchase", "refund-receipt", "sales-receipt", "transfer", "vendor-credit"],
            "description": "QBO transaction type to create, update, or delete."
          },
          "payload": {
            "type": "object",
            "description": "Source QBO payload for the transaction entity."
          },
          "syncToken": {
            "type": "string",
            "description": "Required for delete. For update, include SyncToken inside payload."
          }
        },
        "required": ["entityType"]
      },
      "TransactionWriteResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "clientId": { "type": "string" },
              "qboCompanyId": { "type": "string" },
              "entityType": { "type": "string" },
              "transactionId": { "type": "string" },
              "operation": { "type": "string", "enum": ["create", "update", "delete"] },
              "source": { "type": "string", "const": "qbo" },
              "postedAt": { "type": "string" },
              "data": { "type": "object" }
            },
            "required": ["clientId", "qboCompanyId", "entityType", "operation", "source", "postedAt", "data"]
          }
        },
        "required": ["data"]
      }
    }
  }
}