{ "openapi": "3.1.0", "info": { "title": "GAAPx Accounting Automation & Revenue Recognition API", "version": "1.0.0", "description": "GAAPx 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 Multi-Language SDK Packages\n- **TypeScript / Node.js**: `@gaapx/sdk` ([npm](https://www.npmjs.com/package/@gaapx/sdk)) — `npm install @gaapx/sdk`\n- **Python**: `gaapx-sdk` ([PyPI](https://pypi.org/project/gaapx-sdk/)) — `pip install gaapx-sdk`\n- **Go**: `github.com/gaapx/gaapx-go` ([pkg.go.dev](https://pkg.go.dev/github.com/gaapx/gaapx-go)) — `go get github.com/gaapx/gaapx-go`\n- **Ruby**: `gaapx-ruby` ([RubyGems](https://rubygems.org/gems/gaapx-ruby)) — `gem install gaapx-ruby`\n\n### Versioning & Deprecation Policy\nAll GAAPx 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 alongside a `Link: ; rel=\"sunset\"` header. Full documentation at [https://docs.gaapx.ai/versioning.md](https://docs.gaapx.ai/versioning.md).\n\n### Free Instant Developer Sandbox\nInstant access with bearer token `test_sk_gaapx_sandbox_free_tier` against `https://sandbox.gaapx.ai/v1` or `https://docs.gaapx.ai/api/v1` without credit card or sales contact.\n\n### Machine Payments Protocol (MPP)\nGAAPx supports autonomous agent machine-to-machine payments via MPP over HTTP 402 with `WWW-Authenticate: Payment` challenges.", "contact": { "name": "GAAPx Developer Relations", "url": "https://docs.gaapx.ai", "email": "support@gaapx.ai" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" } }, "externalDocs": { "description": "GAAPx Documentation, Multi-Language SDKs & MCP Guides", "url": "https://docs.gaapx.ai/docs/integrations/sdks" }, "x-payment-info": { "protocol": "mpp/1.0", "methods": ["stripe", "usdc", "tempo"], "currency": "USD", "pricing": { "developer_sandbox": 0, "growth": 499, "scale": 1499 }, "endpoints": { "/contracts": { "price": "0.00", "currency": "USD", "method": "free_tier" }, "/waterfalls": { "price": "0.00", "currency": "USD", "method": "free_tier" }, "/disclosures/note6": { "price": "0.00", "currency": "USD", "method": "free_tier" } }, "challenge_header": "WWW-Authenticate: Payment realm=\"GAAPx Premium Accounting\", method=\"stripe,usdc,tempo\", intent_url=\"https://docs.gaapx.ai/api/v1/payments/intent\"" }, "x-sdks": [ { "language": "typescript", "package": "@gaapx/sdk", "registry": "npm", "url": "https://www.npmjs.com/package/@gaapx/sdk", "repository": "https://github.com/gaapx/gaapx-node", "homepage": "https://docs.gaapx.ai" }, { "language": "python", "package": "gaapx-sdk", "registry": "pypi", "url": "https://pypi.org/project/gaapx-sdk/", "repository": "https://github.com/gaapx/gaapx-python", "homepage": "https://docs.gaapx.ai" }, { "language": "go", "package": "github.com/gaapx/gaapx-go", "registry": "go", "url": "https://pkg.go.dev/github.com/gaapx/gaapx-go", "repository": "https://github.com/gaapx/gaapx-go", "homepage": "https://docs.gaapx.ai" }, { "language": "ruby", "package": "gaapx-ruby", "registry": "rubygems", "url": "https://rubygems.org/gems/gaapx-ruby", "repository": "https://github.com/gaapx/gaapx-ruby", "homepage": "https://docs.gaapx.ai" } ], "servers": [ { "url": "https://sandbox.gaapx.ai/v1", "description": "GAAPx Self-Serve Free Sandbox Environment (Instant Access with test_sk_gaapx_sandbox_free_tier)" }, { "url": "https://docs.gaapx.ai/api/v1", "description": "GAAPx Interactive Documentation & Sandbox Gateway" }, { "url": "https://api.gaapx.ai/v1", "description": "GAAPx Production API" } ], "paths": { "/contracts": { "get": { "summary": "GAAPx Search & List Contracts", "operationId": "listContracts", "description": "Search and retrieve customer MSAs, order forms, and amendment lineages with GAAPx.", "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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["read:contracts"] }, { "OAuth2": ["read:contracts"] }] }, "post": { "summary": "GAAPx Ingest Contract", "operationId": "ingestContract", "description": "Ingest a new multi-element contract into GAAPx 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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["write:contracts"] }, { "OAuth2": ["write:contracts"] }] } }, "/waterfalls": { "get": { "summary": "GAAPx 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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["read:waterfalls"] }, { "OAuth2": ["read:waterfalls"] }] } }, "/disclosures/note6": { "get": { "summary": "GAAPx 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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["read:disclosures"] }, { "OAuth2": ["read:disclosures"] }] } }, "/payments/challenge": { "get": { "summary": "GAAPx MPP Payment Challenge", "operationId": "getPaymentChallenge", "description": "Returns HTTP 402 Payment Required with WWW-Authenticate: Payment challenge for Machine Payments Protocol (MPP) autonomous agent settlement.", "responses": { "402": { "$ref": "#/components/responses/PaymentRequiredError" } } } }, "/payments/intent": { "get": { "summary": "GAAPx MPP Payment Intent & Information", "operationId": "getPaymentIntent", "description": "Inspect Machine Payments Protocol (MPP) merchant configuration, supported rails (Stripe, USDC, Tempo), and per-call rates.", "responses": { "200": { "description": "Payment intent information", "content": { "application/json": { "schema": { "type": "object", "properties": { "protocol": { "type": "string", "example": "mpp/1.0" }, "merchant": { "type": "string", "example": "GAAPx Inc." }, "supported_methods": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "string", "example": "USD" } }, "required": ["protocol", "merchant", "supported_methods", "currency"] } } } } } } }, "/batch": { "post": { "summary": "GAAPx 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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["write:contracts"] }] } }, "/jobs/recalculate-waterfall": { "post": { "summary": "GAAPx 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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["write:contracts"] }] } }, "/jobs/{job_id}": { "get": { "summary": "GAAPx Get Async Job Status", "operationId": "getJobStatus", "description": "Poll the status of an asynchronous background job in GAAPx.", "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/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "402": { "$ref": "#/components/responses/PaymentRequiredError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/NotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" }, "429": { "$ref": "#/components/responses/RateLimitError" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [{ "BearerAuth": ["read:contracts"] }] } } }, "components": { "schemas": { "Contract": { "type": "object", "properties": { "id": { "type": "string", "example": "cntr_acme_101" }, "customer_name": { "type": "string", "example": "Acme Enterprises" }, "total_value": { "type": "number", "example": 120000 }, "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-12-31" }, "status": { "type": "string", "enum": ["active", "draft", "terminated"], "example": "active" } }, "required": ["id", "customer_name", "total_value", "start_date", "end_date", "status"] }, "ContractInput": { "type": "object", "properties": { "customer_name": { "type": "string", "example": "Acme Enterprises" }, "total_value": { "type": "number", "example": 120000 }, "start_date": { "type": "string", "format": "date", "example": "2026-01-01" }, "end_date": { "type": "string", "format": "date", "example": "2026-12-31" } }, "required": ["customer_name", "total_value", "start_date", "end_date"] }, "WaterfallPeriod": { "type": "object", "properties": { "period": { "type": "string", "example": "2026-01" }, "recognized_amount": { "type": "number", "example": 10000 }, "deferred_balance": { "type": "number", "example": 110000 } }, "required": ["period", "recognized_amount", "deferred_balance"] }, "ErrorModel": { "type": "object", "description": "Standard RFC 9457 Problem Details error schema with typed error code and actionable guidance.", "properties": { "type": { "type": "string", "format": "uri", "example": "https://docs.gaapx.ai/errors/invalid-request", "description": "URI reference identifying the problem type" }, "title": { "type": "string", "example": "Invalid Request", "description": "Short human-readable summary" }, "status": { "type": "integer", "example": 400, "description": "HTTP status code" }, "detail": { "type": "string", "example": "Period must be in YYYY-MM format, e.g. 2026-01", "description": "Human-readable explanation specific to this occurrence" }, "instance": { "type": "string", "format": "uri", "example": "/v1/waterfalls?period=invalid", "description": "URI reference identifying the specific occurrence" }, "code": { "type": "string", "example": "INVALID_PERIOD_FORMAT", "description": "Machine-readable structured error code" }, "message": { "type": "string", "example": "The requested period parameter format is invalid", "description": "Human-readable message" }, "hint": { "type": "string", "example": "Pass period formatted as YYYY-MM (e.g., '2026-01')", "description": "Actionable suggestion for autonomous agent resolution" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "required": ["type", "title", "status", "code", "message"] } }, "responses": { "BadRequestError": { "description": "400 Bad Request — Invalid parameters or malformed JSON payload", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "UnauthorizedError": { "description": "401 Unauthorized — Missing or invalid Bearer authentication token", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "RFC 9728 OAuth resource metadata link" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "PaymentRequiredError": { "description": "402 Payment Required — Machine Payments Protocol (MPP) challenge", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "description": "MPP payment challenge (e.g., Payment realm=\"GAAPx Premium Accounting\", method=\"stripe,usdc\", intent_url=\"...\")" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "ForbiddenError": { "description": "403 Forbidden — Insufficient scope or permissions for the requested resource", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "NotFoundError": { "description": "404 Not Found — The specified resource was not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "UnprocessableEntityError": { "description": "422 Unprocessable Entity — Validation error on payload fields", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "RateLimitError": { "description": "429 Too Many Requests — Rate limit exceeded", "headers": { "RateLimit-Limit": { "schema": { "type": "integer" } }, "RateLimit-Remaining": { "schema": { "type": "integer" } }, "RateLimit-Reset": { "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } }, "InternalServerError": { "description": "500 Internal Server Error — Unexpected server-side fault", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ErrorModel" } } } } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "GAAPx instant sandbox key (`test_sk_gaapx_sandbox_free_tier`) or production API token" }, "OAuth2": { "type": "oauth2", "description": "GAAPx 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" } } } } } } }