{
  "openapi": "3.1.0",
  "info": {
    "title": "Hoist Assets API",
    "description": "PPSR + ABN due diligence for Australian asset finance. Org-only scope (organisation-grantor + serial-number searches, no PII) — does not search individuals.",
    "version": "1.0.0",
    "termsOfService": "https://assets.hoistai.com/terms/",
    "contact": {
      "name": "Hoist Assets",
      "email": "hello@hoistai.com",
      "url": "https://assets.hoistai.com/contact/"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://assets.hoistai.com/terms/"
    }
  },
  "servers": [
    {
      "url": "https://api.assets.hoistai.com/v1",
      "description": "Production"
    },
    {
      "url": "https://api.assets.hoistai.com/v1?sandbox=true",
      "description": "Sandbox (fixtures only)"
    }
  ],
  "components": {
    "schemas": {
      "AbnLookupError": {
        "type": "object",
        "required": ["ok", "code", "message"],
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false,
            "description": "Always false on a non-2xx response"
          },
          "code": {
            "type": "string",
            "enum": [
              "invalid_abn",
              "abn_not_found",
              "rate_limited",
              "upstream_error",
              "network_error",
              "parse_error"
            ],
            "description": "Stable error sentinel. Clients should branch on this rather than parsing message."
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message. May change between releases — do not parse."
          }
        }
      }
    },
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API-Key"
      },
      "oauth2": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://assets.hoistai.com/oauth/authorize",
            "tokenUrl": "https://assets.hoistai.com/oauth/token",
            "scopes": {
              "search:read": "Read records you've created",
              "search:write": "Run paid PPSR/ABN searches",
              "batch:write": "Kick off CSV batches",
              "exports:write": "Generate evidence packs",
              "billing:read": "Read usage and allowance"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "apiKey": []
    },
    {
      "oauth2": [
        "search:write"
      ]
    }
  ],
  "paths": {
    "/_health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Liveness probe",
        "description": "Returns a public health envelope confirming the API is reachable. No authentication required. Status: live (promoted from roadmap by ha-h4ec).",
        "security": [],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["ok", "version", "time"],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true,
                      "description": "Always true on a 200 response"
                    },
                    "version": {
                      "type": "string",
                      "description": "Worker package version (semver)",
                      "example": "0.0.700"
                    },
                    "time": {
                      "type": "string",
                      "format": "date-time",
                      "description": "ISO 8601 timestamp of the probe",
                      "example": "2026-05-20T12:00:00.000Z"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/ppsr/search": {
      "post": {
        "summary": "PPSR organisation or serial-number search",
        "description": "Runs an official AFSA PPSR search. Org-only scope (organisations and serial numbers). Requires search:write."
      }
    },
    "/ppsr/batch": {
      "post": {
        "summary": "Batch PPSR (CSV in, ZIP out)"
      }
    },
    "/abn/{abn}": {
      "get": {
        "operationId": "abnLookup",
        "summary": "ABN lookup",
        "description": "Look up an Australian Business Number against the Australian Business Register. Returns the entity name, type, status, and registered address summary. Org-only — does not search individuals. Status: live (promoted from roadmap by ha-300s — first Rule 31 three-tier feature).",
        "security": [],
        "parameters": [
          {
            "name": "abn",
            "in": "path",
            "required": true,
            "description": "11-digit Australian Business Number. Spaces and hyphens are accepted and stripped server-side.",
            "schema": {
              "type": "string",
              "pattern": "^[0-9 -]{11,16}$",
              "example": "12 345 678 901"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ABN found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "abn",
                    "entityName",
                    "entityType",
                    "status",
                    "abnRegisteredDate",
                    "acn",
                    "state",
                    "postcode"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "const": true,
                      "description": "Always true on a 200 response"
                    },
                    "abn": {
                      "type": "string",
                      "description": "Normalised 11-digit ABN (no spaces)",
                      "example": "12345678901"
                    },
                    "entityName": {
                      "type": "string",
                      "description": "Registered entity name from the ABR",
                      "example": "MOCK BUILDING SUPPLIES PTY LTD"
                    },
                    "entityType": {
                      "type": "string",
                      "description": "Entity type (e.g. Australian Private Company, Partnership)",
                      "example": "Australian Private Company"
                    },
                    "status": {
                      "type": "string",
                      "description": "Current ABN status: Active or Cancelled",
                      "example": "Active"
                    },
                    "abnRegisteredDate": {
                      "type": "string",
                      "description": "ISO date the ABN was first registered",
                      "example": "2010-03-15"
                    },
                    "acn": {
                      "type": ["string", "null"],
                      "description": "ACN if the entity has one (companies + registered bodies); null otherwise",
                      "example": "123 456 789"
                    },
                    "state": {
                      "type": ["string", "null"],
                      "description": "Primary business location state code (NSW/VIC/etc.) or null",
                      "example": "NSW"
                    },
                    "postcode": {
                      "type": ["string", "null"],
                      "description": "Primary business location postcode or null",
                      "example": "2000"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid ABN input",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AbnLookupError" }
              }
            }
          },
          "404": {
            "description": "ABN not found",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AbnLookupError" }
              }
            }
          },
          "429": {
            "description": "Upstream rate limit hit",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AbnLookupError" }
              }
            }
          },
          "502": {
            "description": "Upstream ABR error (network / parse / non-2xx)",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AbnLookupError" }
              }
            }
          }
        }
      }
    },
    "/abn/{abn}/history": {
      "get": {
        "summary": "ABN history"
      }
    },
    "/gst/{abn}": {
      "get": {
        "summary": "GST registration as at date"
      }
    },
    "/records/{id}": {
      "get": {
        "summary": "Retrieve a record (PDF or JSON)"
      }
    },
    "/records/{id}/verify": {
      "get": {
        "summary": "Verify a record hash"
      }
    },
    "/records": {
      "get": {
        "summary": "List recent records"
      }
    },
    "/exports": {
      "post": {
        "summary": "Create an evidence-pack ZIP"
      }
    },
    "/usage": {
      "get": {
        "summary": "Current usage and remaining allowance"
      }
    }
  },
  "x-org-only-scope": "Hoist Assets operates under an org-only scope: organisation-grantor and serial-number searches only, no PII. The API does NOT accept individual-grantor searches and will reject them with a 400 response before any search runs. See https://assets.hoistai.com/trust/npii-boundary."
}