{
  "openapi": "3.1.0",
  "info": {
    "title": "Sealith Agent API",
    "version": "1.2.0",
    "description": "Purpose-bound secure handoff APIs for AI agents. Business plan or higher is required."
  },
  "servers": [
    {
      "url": "https://www.sealith.com"
    }
  ],
  "security": [
    {
      "AgentToken": []
    }
  ],
  "components": {
    "securitySchemes": {
      "AgentToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "Use an Agent Token secret issued from the Sealith dashboard."
      }
    },
    "schemas": {
      "Recipient": {
        "type": "object",
        "required": ["email"],
        "properties": {
          "email": {
            "type": "string",
            "format": "email"
          },
          "name": {
            "type": ["string", "null"]
          }
        }
      },
      "TransferPayload": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "fileName",
              "fileSizeBytes",
              "mimeType",
              "recipients",
              "salt",
              "ivFile",
              "ivWrap",
              "passcodeHash",
              "expiresAt",
              "maxDownloads",
              "passcodeDeliveryMode",
              "sensitivityLevel"
            ],
            "properties": {
              "resourceType": {
                "type": "string",
                "enum": ["file"],
                "default": "file"
              },
              "fileName": {
                "type": "string",
                "maxLength": 255
              },
              "fileSizeBytes": {
                "type": "integer",
                "minimum": 1
              },
              "mimeType": {
                "type": "string"
              },
              "recipients": {
                "type": "array",
                "minItems": 1,
                "maxItems": 10,
                "items": {
                  "$ref": "#/components/schemas/Recipient"
                }
              },
              "message": {
                "type": ["string", "null"],
                "maxLength": 500
              },
              "salt": {
                "type": "string"
              },
              "ivFile": {
                "type": "string"
              },
              "ivWrap": {
                "type": "string"
              },
              "passcodeHash": {
                "type": "string"
              },
              "senderAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "systemAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "maxDownloads": {
                "type": ["integer", "null"],
                "enum": [1, 3, 5, 10, 20, null]
              },
              "passcodeDeliveryMode": {
                "type": "string",
                "enum": ["A", "B"]
              },
              "sensitivityLevel": {
                "type": "string",
                "enum": ["public", "internal", "confidential", "restricted"]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "resourceType",
              "title",
              "targetUrl",
              "targetDomain",
              "recipients",
              "passcodeHash",
              "expiresAt",
              "maxDownloads",
              "passcodeDeliveryMode",
              "sensitivityLevel"
            ],
            "properties": {
              "resourceType": {
                "type": "string",
                "enum": ["url"]
              },
              "title": {
                "type": "string",
                "maxLength": 255
              },
              "targetUrl": {
                "type": "string",
                "format": "uri"
              },
              "targetDomain": {
                "type": "string"
              },
              "recipients": {
                "type": "array",
                "minItems": 1,
                "maxItems": 10,
                "items": {
                  "$ref": "#/components/schemas/Recipient"
                }
              },
              "message": {
                "type": ["string", "null"],
                "maxLength": 500
              },
              "passcodeHash": {
                "type": "string"
              },
              "senderAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "systemAccessiblePasscode": {
                "type": ["string", "null"]
              },
              "expiresAt": {
                "type": "string",
                "format": "date-time"
              },
              "maxDownloads": {
                "type": ["integer", "null"],
                "enum": [1, 3, 5, 10, 20, null]
              },
              "passcodeDeliveryMode": {
                "type": "string",
                "enum": ["A", "B"]
              },
              "sensitivityLevel": {
                "type": "string",
                "enum": ["public", "internal", "confidential", "restricted"]
              }
            }
          }
        ]
      },
      "TransferCreateInput": {
        "type": "object",
        "required": ["purpose", "transfer"],
        "properties": {
          "purpose": {
            "type": "string",
            "maxLength": 120
          },
          "jobId": {
            "type": ["string", "null"],
            "maxLength": 160
          },
          "transfer": {
            "$ref": "#/components/schemas/TransferPayload"
          }
        }
      },
      "TransferCreateResponse": {
        "type": "object",
        "required": ["transferId", "uploadUrl", "expiresIn", "shareUrlPath", "passcodeScheduledSendAt"],
        "properties": {
          "transferId": {
            "type": "string"
          },
          "uploadUrl": {
            "type": ["string", "null"],
            "format": "uri"
          },
          "expiresIn": {
            "type": "integer"
          },
          "shareUrlPath": {
            "type": "string"
          },
          "passcodeScheduledSendAt": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        }
      },
      "TransferRecipientStatus": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Recipient"
          },
          {
            "type": "object",
            "properties": {
              "notifiedUrlAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "notifiedPasscodeAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "firstAccessedAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "downloadCount": {
                "type": "integer"
              }
            }
          }
        ]
      },
      "TransferStatusResponse": {
        "type": "object",
        "required": ["transfer"],
        "properties": {
          "transfer": {
            "type": "object",
            "required": [
              "id",
              "fileName",
              "fileSizeBytes",
              "mimeType",
              "recipients",
              "status",
              "expiresAt",
              "maxDownloads",
              "totalDownloadCount",
              "passcodeDeliveryMode",
              "passcodeScheduledSendAt",
              "createdAt"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "fileName": {
                "type": "string"
              },
              "fileSizeBytes": {
                "type": "integer"
              },
              "mimeType": {
                "type": "string"
              },
              "recipients": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/TransferRecipientStatus"
                }
              },
              "status": {
                "type": "string"
              },
              "expiresAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "maxDownloads": {
                "type": ["integer", "null"]
              },
              "totalDownloadCount": {
                "type": "integer"
              },
              "passcodeDeliveryMode": {
                "type": "string",
                "enum": ["A", "B"]
              },
              "passcodeScheduledSendAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "createdAt": {
                "type": ["string", "null"],
                "format": "date-time"
              },
              "resourceType": {
                "type": "string",
                "enum": ["file", "url"]
              },
              "title": {
                "type": ["string", "null"]
              },
              "targetUrl": {
                "type": ["string", "null"],
                "format": "uri"
              },
              "targetDomain": {
                "type": ["string", "null"]
              }
            }
          }
        }
      },
      "FinalizeTransferInput": {
        "type": "object",
        "required": ["shareUrl"],
        "properties": {
          "shareUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "AppendAuditContextInput": {
        "type": "object",
        "required": ["transferId", "purpose", "note"],
        "properties": {
          "transferId": {
            "type": "string"
          },
          "purpose": {
            "type": "string"
          },
          "jobId": {
            "type": ["string", "null"]
          },
          "note": {
            "type": "string"
          },
          "result": {
            "type": ["string", "null"]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          }
        }
      },
      "AccessLogEntry": {
        "type": "object",
        "properties": {
          "id": {
            "type": ["string", "null"]
          },
          "sequence": {
            "type": ["integer", "null"]
          },
          "eventHash": {
            "type": ["string", "null"]
          },
          "previousHash": {
            "type": ["string", "null"]
          },
          "canonicalPayloadHash": {
            "type": ["string", "null"]
          },
          "hashAlgorithm": {
            "type": ["string", "null"]
          },
          "eventTime": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "eventType": {
            "type": "string"
          },
          "actorType": {
            "type": "string"
          },
          "actorId": {
            "type": ["string", "null"]
          },
          "actorName": {
            "type": ["string", "null"]
          },
          "actorEmail": {
            "type": ["string", "null"]
          },
          "tokenId": {
            "type": ["string", "null"]
          },
          "purpose": {
            "type": ["string", "null"]
          },
          "jobId": {
            "type": ["string", "null"]
          },
          "scope": {
            "type": ["string", "null"]
          },
          "success": {
            "type": "boolean"
          },
          "errorCode": {
            "type": ["string", "null"]
          },
          "metadata": {
            "type": "object",
            "additionalProperties": true
          },
          "createdAt": {
            "type": ["string", "null"],
            "format": "date-time"
          }
        }
      },
      "LogsResponse": {
        "type": "object",
        "required": ["logs"],
        "properties": {
          "logs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AccessLogEntry"
            }
          }
        }
      },
      "OkResponse": {
        "type": "object",
        "required": ["ok"],
        "properties": {
          "ok": {
            "type": "boolean"
          }
        }
      },
      "TransferSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "resourceType": { "type": "string", "enum": ["file", "url"] },
          "fileName": { "type": "string" },
          "title": { "type": ["string", "null"] },
          "status": { "type": "string" },
          "recipients": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "email": { "type": "string" },
                "name": { "type": ["string", "null"] },
                "firstAccessedAt": { "type": ["string", "null"], "format": "date-time" },
                "downloadCount": { "type": "integer" }
              }
            }
          },
          "totalDownloadCount": { "type": "integer" },
          "maxDownloads": { "type": ["integer", "null"] },
          "expiresAt": { "type": ["string", "null"], "format": "date-time" },
          "purpose": { "type": ["string", "null"] },
          "jobId": { "type": ["string", "null"] },
          "sensitivityLevel": { "type": ["string", "null"] },
          "createdAt": { "type": ["string", "null"], "format": "date-time" }
        }
      },
      "TransferListResponse": {
        "type": "object",
        "required": ["transfers", "total"],
        "properties": {
          "transfers": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/TransferSummary" }
          },
          "total": { "type": "integer" }
        }
      },
      "BulkRevokeInput": {
        "type": "object",
        "required": ["action", "transferIds"],
        "properties": {
          "action": { "type": "string", "enum": ["revoke"] },
          "transferIds": {
            "type": "array",
            "items": { "type": "string" },
            "minItems": 1,
            "maxItems": 20
          },
          "reason": { "type": ["string", "null"], "maxLength": 200 }
        }
      },
      "BulkRevokeResponse": {
        "type": "object",
        "required": ["ok", "revokedCount"],
        "properties": {
          "ok": { "type": "boolean" },
          "revokedCount": { "type": "integer" }
        }
      },
      "OrgUsageResponse": {
        "type": "object",
        "properties": {
          "plan": { "type": "string" },
          "limits": {
            "type": "object",
            "properties": {
              "maxMonthlyTransfers": { "type": ["integer", "null"] },
              "maxFileSizeMB": { "type": ["integer", "null"] },
              "maxRecipients": { "type": ["integer", "null"] },
              "maxRetentionDays": { "type": ["integer", "null"] }
            }
          },
          "usage": {
            "type": "object",
            "properties": {
              "currentMonthTransfers": { "type": "integer" },
              "remainingMonthlyTransfers": { "type": ["integer", "null"] },
              "resetAt": { "type": ["string", "null"] }
            }
          },
          "capabilities": {
            "type": "object",
            "properties": {
              "mcp": { "type": "boolean" },
              "agentTokens": { "type": "boolean" },
              "archive": { "type": "boolean" },
              "openNotification": { "type": "boolean" },
              "auditCsvExport": { "type": "boolean" }
            }
          }
        }
      },
      "AuditVerifyResponse": {
        "type": "object",
        "required": ["ok", "checked", "verified", "legacy", "failures"],
        "properties": {
          "ok": { "type": "boolean" },
          "checked": { "type": "integer" },
          "verified": { "type": "integer" },
          "legacy": { "type": "integer" },
          "failures": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "sequence": { "type": ["integer", "null"] },
                "reason": { "type": "string" }
              }
            }
          },
          "latestHash": { "type": ["string", "null"] },
          "summary": { "type": "string" }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": ["string", "null"]
          },
          "issues": {
            "type": ["object", "null"],
            "additionalProperties": true
          },
          "status": {
            "type": ["string", "null"]
          },
          "email": {
            "type": ["string", "null"]
          },
          "maxFileSizeMB": {
            "type": ["integer", "null"]
          },
          "maxDays": {
            "type": ["integer", "null"]
          },
          "maxMonthlyTransfers": {
            "type": ["integer", "null"]
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid Agent Token",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "examples": {
              "agent_unauthorized": {
                "value": {
                  "error": "agent_unauthorized"
                }
              },
              "invalid_agent_token": {
                "value": {
                  "error": "invalid_agent_token"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Plan or policy restriction",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Transfer not found",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "not_found"
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "Schema validation failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            },
            "example": {
              "error": "invalid_request",
              "issues": {}
            }
          }
        }
      }
    }
  },
  "paths": {
    "/api/agent/transfers": {
      "get": {
        "summary": "List and search handoffs",
        "operationId": "listHandoffs",
        "parameters": [
          { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "Keyword search across fileName, title, purpose, jobId, recipient emails" },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["draft", "active", "revoked", "expired", "exhausted"] } },
          { "name": "resourceType", "in": "query", "schema": { "type": "string", "enum": ["file", "url"] } },
          { "name": "recipientEmail", "in": "query", "schema": { "type": "string", "format": "email" } },
          { "name": "dateFrom", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD inclusive start" },
          { "name": "dateTo", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "YYYY-MM-DD inclusive end" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }
        ],
        "responses": {
          "200": {
            "description": "List of transfers matching filters",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TransferListResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      },
      "post": {
        "summary": "Create a file or URL handoff",
        "operationId": "createSecureHandoff",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferCreateInput"
              },
              "example": {
                "purpose": "contract_review",
                "jobId": "job_20260423_001",
                "transfer": {
                  "fileName": "nda.pdf",
                  "fileSizeBytes": 524288,
                  "mimeType": "application/pdf",
                  "recipients": [
                    {
                      "email": "legal@example.com",
                      "name": "Legal"
                    }
                  ],
                  "message": "Please review.",
                  "salt": "base64url-salt",
                  "ivFile": "base64url-file-iv",
                  "ivWrap": "base64url-wrap-iv",
                  "passcodeHash": "argon2id-passcode-hash",
                  "senderAccessiblePasscode": null,
                  "systemAccessiblePasscode": "kms-wrapped-passcode",
                  "expiresAt": "2026-04-30T12:00:00.000Z",
                  "maxDownloads": 3,
                  "passcodeDeliveryMode": "B",
                  "sensitivityLevel": "confidential"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer metadata. File handoffs include uploadUrl; URL handoffs return null for uploadUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferCreateResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/agent/transfers/{id}": {
      "get": {
        "summary": "Get handoff status",
        "operationId": "getSecureHandoffStatus",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferStatusResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/{id}/finalize": {
      "post": {
        "summary": "Finalize uploaded handoff",
        "operationId": "finalizeSecureHandoff",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FinalizeTransferInput"
              },
              "example": {
                "shareUrl": "https://www.sealith.com/r/tr_xxxxxxxxxxxxxxxx"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfer finalized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/{id}/revoke": {
      "post": {
        "summary": "Revoke handoff",
        "operationId": "revokeSecureHandoff",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transfer revoked",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/{id}/logs": {
      "get": {
        "summary": "Read audit logs",
        "operationId": "getSecureHandoffLogs",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit log entries",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LogsResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/receive": {
      "post": {
        "summary": "Receive a handoff as an AI recipient",
        "operationId": "receiveSecureHandoff",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["transferId", "passcode", "purpose"],
                "properties": {
                  "transferId": { "type": "string" },
                  "passcode": { "type": "string" },
                  "purpose": { "type": "string" },
                  "recipientEmail": { "type": "string", "format": "email" }
                }
              },
              "example": {
                "transferId": "tr_xxxxxxxxxxxxxxxx",
                "passcode": "A2b!C3d@E4f#G5h$",
                "purpose": "contract_review",
                "recipientEmail": "legal@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "For file handoffs, returns a signed download URL and crypto parameters. For URL handoffs, returns targetUrl metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "resourceType": { "type": "string", "enum": ["file"] },
                        "signedUrl": { "type": "string" },
                        "fileName": { "type": "string" },
                        "fileSizeBytes": { "type": "integer" },
                        "mimeType": { "type": "string" },
                        "ciphertext": {
                          "type": "object",
                          "properties": {
                            "expiresIn": { "type": "integer" }
                          }
                        },
                        "crypto": {
                          "type": "object",
                          "properties": {
                            "salt": { "type": "string" },
                            "ivFile": { "type": "string" },
                            "ivWrap": { "type": "string" }
                          }
                        },
                        "metadata": {
                          "type": "object",
                          "properties": {
                            "senderEmail": { "type": "string", "nullable": true },
                            "senderDisplayName": { "type": "string", "nullable": true },
                            "message": { "type": "string", "nullable": true }
                          }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "resourceType": { "type": "string", "enum": ["url"] },
                        "link": {
                          "type": "object",
                          "properties": {
                            "targetUrl": { "type": "string", "format": "uri" },
                            "targetDomain": { "type": "string" },
                            "title": { "type": "string" }
                          }
                        },
                        "metadata": {
                          "type": "object",
                          "properties": {
                            "senderEmail": { "type": "string", "nullable": true },
                            "senderDisplayName": { "type": "string", "nullable": true },
                            "message": { "type": "string", "nullable": true }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/agent/transfers/bulk": {
      "post": {
        "summary": "Bulk revoke handoffs",
        "operationId": "bulkRevokeHandoffs",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/BulkRevokeInput" },
              "example": {
                "action": "revoke",
                "transferIds": ["tr_xxxxxxxxxxxxxxxx", "tr_yyyyyyyyyyyyyyyy"],
                "reason": "プロジェクト終了のため"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Transfers revoked",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/BulkRevokeResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/agent/org/usage": {
      "get": {
        "summary": "Get organization plan limits and usage",
        "operationId": "getOrgUsage",
        "responses": {
          "200": {
            "description": "Plan limits and current month usage statistics",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/OrgUsageResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/agent/org/audit/verify": {
      "get": {
        "summary": "Verify audit log chain integrity",
        "operationId": "verifyAuditIntegrity",
        "responses": {
          "200": {
            "description": "SHA-256 hash chain verification result for all audit logs",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/AuditVerifyResponse" }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/agent/audit-context": {
      "post": {
        "summary": "Append audit context",
        "operationId": "appendAuditContext",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppendAuditContextInput"
              },
              "example": {
                "transferId": "tr_xxxxxxxxxxxxxxxx",
                "purpose": "contract_review",
                "jobId": "job_20260423_001",
                "note": "Key clauses extracted for human review.",
                "result": "needs_human_review",
                "metadata": {
                  "model": "gpt-5.4",
                  "reviewCount": 4
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit context appended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OkResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  }
}