{
  "openapi": "3.1.0",
  "info": {
    "title": "GAAPx Accounting Automation & Revenue Recognition API",
    "version": "1.0.0",
    "description": "Deterministic ASC 606 & IFRS 15 revenue recognition, waterfall schedules, and Note 6 disclosure generation API for SaaS, CPQ systems, and autonomous AI finance agents.\n\n### Official SDK Packages\n- **TypeScript / Node.js**: `@gaapx/sdk` ([npm](https://www.npmjs.com/package/@gaapx/sdk))\n- **Python**: `gaapx-sdk` ([PyPI](https://pypi.org/project/gaapx-sdk/))\n- **Go**: `github.com/gaapx/gaapx-go`\n- **Ruby**: `gaapx-ruby` ([RubyGems](https://rubygems.org/gems/gaapx-ruby))\n\n### Versioning & Deprecation Policy\nAll endpoints are versioned under `/v1`. Backward-incompatible changes trigger a new major version. Deprecated endpoints are announced 180 days in advance and return standard `Deprecation` and `Sunset` HTTP response headers.",
    "contact": {
      "name": "GAAPx Developer Relations",
      "url": "https://docs.gaapx.ai",
      "email": "support@gaapx.ai"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.gaapx.ai/v1",
      "description": "Self-Serve Free Sandbox Environment (Instant Access with test_sk_gaapx_sandbox_free_tier)"
    },
    {
      "url": "https://docs.gaapx.ai/api/v1",
      "description": "Interactive Documentation & Sandbox Gateway"
    },
    {
      "url": "https://api.gaapx.ai/v1",
      "description": "Production API"
    }
  ],
  "paths": {
    "/contracts": {
      "get": {
        "summary": "List & Search Contracts",
        "operationId": "listContracts",
        "description": "Search and retrieve customer MSAs, order forms, and amendment lineages.",
        "parameters": [
          { "name": "query", "in": "query", "schema": { "type": "string" }, "description": "Search keyword" },
          { "name": "customer_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by customer ID" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["active", "draft", "terminated"] }, "description": "Contract status" }
        ],
        "responses": {
          "200": {
            "description": "List of matching contracts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/Contract" }
                    },
                    "total": { "type": "integer" }
                  },
                  "required": ["data", "total"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["read:contracts"] }, { "OAuth2": ["read:contracts"] }]
      },
      "post": {
        "summary": "Ingest Contract",
        "operationId": "ingestContract",
        "description": "Ingest a new multi-element contract for AI extraction and POB breakdown.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": { "type": "string" },
            "description": "Unique key to prevent duplicate processing on retries"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/ContractInput" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Contract created and queued for parsing",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Contract" }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["write:contracts"] }, { "OAuth2": ["write:contracts"] }]
      }
    },
    "/waterfalls": {
      "get": {
        "summary": "Get Revenue Recognition Waterfalls",
        "operationId": "getRevenueWaterfalls",
        "description": "Calculate and return monthly revenue recognition waterfalls and deferred balances under ASC 606.",
        "parameters": [
          { "name": "start_period", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-01" },
          { "name": "end_period", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026-12" },
          { "name": "contract_id", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Revenue waterfall schedule",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "periods": {
                      "type": "array",
                      "items": { "$ref": "#/components/schemas/WaterfallPeriod" }
                    },
                    "total_recognized": { "type": "number" },
                    "total_deferred": { "type": "number" }
                  },
                  "required": ["periods", "total_recognized", "total_deferred"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["read:waterfalls"] }, { "OAuth2": ["read:waterfalls"] }]
      }
    },
    "/disclosures/note6": {
      "get": {
        "summary": "Generate Note 6 Disclosures",
        "operationId": "getNote6Disclosures",
        "description": "Automated ASC 606 Note 6 footnote tables and RPO rollforwards.",
        "parameters": [
          { "name": "period", "in": "query", "required": true, "schema": { "type": "string" }, "example": "2026-Q3" }
        ],
        "responses": {
          "200": {
            "description": "Note 6 disclosure schedules",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "period": { "type": "string" },
                    "rpo_total": { "type": "number" },
                    "disaggregated_revenue": { "type": "object", "additionalProperties": { "type": "number" } }
                  },
                  "required": ["period", "rpo_total", "disaggregated_revenue"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["read:disclosures"] }, { "OAuth2": ["read:disclosures"] }]
      }
    },
    "/batch": {
      "post": {
        "summary": "Execute Batch Operations",
        "operationId": "executeBatch",
        "description": "Execute multiple contract ingestion or schedule calculations in a single bulk request.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": { "type": "string" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "operations": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "method": { "type": "string", "enum": ["POST", "GET", "PUT"] },
                        "path": { "type": "string" },
                        "body": { "type": "object" }
                      },
                      "required": ["method", "path"]
                    }
                  }
                },
                "required": ["operations"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Batch operation results",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "status": { "type": "integer" },
                          "body": { "type": "object" }
                        },
                        "required": ["status"]
                      }
                    }
                  },
                  "required": ["results"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["write:contracts"] }]
      }
    },
    "/jobs/recalculate-waterfall": {
      "post": {
        "summary": "Async Waterfall Recalculation Job",
        "operationId": "createWaterfallRecalculationJob",
        "description": "Trigger an asynchronous bulk recalculation job for large contract ledgers.",
        "parameters": [
          { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } }
        ],
        "responses": {
          "202": {
            "description": "Recalculation job accepted and processing",
            "headers": {
              "Location": { "schema": { "type": "string" }, "description": "URL to poll for job progress" }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["queued", "processing", "completed", "failed"] },
                    "poll_url": { "type": "string" }
                  },
                  "required": ["job_id", "status", "poll_url"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["write:contracts"] }]
      }
    },
    "/jobs/{job_id}": {
      "get": {
        "summary": "Get Async Job Status",
        "operationId": "getJobStatus",
        "description": "Poll the status of an asynchronous background job.",
        "parameters": [
          { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Current status of background job",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job_id": { "type": "string" },
                    "status": { "type": "string", "enum": ["queued", "processing", "completed", "failed"] },
                    "progress": { "type": "number" },
                    "result": { "type": "object" }
                  },
                  "required": ["job_id", "status"]
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/ErrorResponse" },
          "401": { "$ref": "#/components/responses/ErrorResponse" },
          "403": { "$ref": "#/components/responses/ErrorResponse" },
          "404": { "$ref": "#/components/responses/ErrorResponse" },
          "422": { "$ref": "#/components/responses/ErrorResponse" },
          "500": { "$ref": "#/components/responses/ErrorResponse" }
        },
        "security": [{ "BearerAuth": ["read:contracts"] }]
      }
    }
  },
  "components": {
    "schemas": {
      "Contract": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "customer_name": { "type": "string" },
          "total_value": { "type": "number" },
          "start_date": { "type": "string", "format": "date" },
          "end_date": { "type": "string", "format": "date" },
          "status": { "type": "string", "enum": ["active", "draft", "terminated"] }
        },
        "required": ["id", "customer_name", "total_value", "start_date", "end_date", "status"]
      },
      "ContractInput": {
        "type": "object",
        "properties": {
          "customer_name": { "type": "string" },
          "total_value": { "type": "number" },
          "start_date": { "type": "string", "format": "date" },
          "end_date": { "type": "string", "format": "date" }
        },
        "required": ["customer_name", "total_value", "start_date", "end_date"]
      },
      "WaterfallPeriod": {
        "type": "object",
        "properties": {
          "period": { "type": "string" },
          "recognized_amount": { "type": "number" },
          "deferred_balance": { "type": "number" }
        },
        "required": ["period", "recognized_amount", "deferred_balance"]
      },
      "ErrorModel": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "example": "https://docs.gaapx.ai/errors/invalid-request" },
          "title": { "type": "string", "example": "Invalid Request" },
          "status": { "type": "integer", "example": 400 },
          "code": { "type": "string", "example": "INVALID_PERIOD_FORMAT" },
          "message": { "type": "string", "example": "Period must be in YYYY-MM format" },
          "hint": { "type": "string", "example": "Use YYYY-MM such as '2026-01'" }
        },
        "required": ["status", "code", "message"]
      }
    },
    "responses": {
      "ErrorResponse": {
        "description": "Structured RFC 9457 typed JSON error response",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ErrorModel" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorModel" }
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Instant sandbox key (`test_sk_gaapx_sandbox_free_tier`) or production API token"
      },
      "OAuth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 machine-to-machine authentication",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://docs.gaapx.ai/oauth/token",
            "scopes": {
              "read:contracts": "View customer contracts and order forms",
              "write:contracts": "Create and amend contracts",
              "read:waterfalls": "Query ASC 606 revenue recognition waterfalls",
              "read:disclosures": "Generate Note 6 disclosures and audit binders",
              "read:ledger": "Access journal entries and trial balances",
              "execute:mcp": "Invoke Model Context Protocol tools"
            }
          }
        }
      }
    }
  }
}