{ "openapi": "3.1.0", "info": { "title": "Hybrid-Chain app-scoped Data Vault files", "version": "2026-10-20", "description": "Exact file operation and transitive component schemas extracted from the live gateway OpenAPI. Owner enrollment/consent uses the separate Hybrid-ID owner API." }, "servers": [ { "url": "https://api.hybrid-chain.com" } ], "paths": { "/api/v2/data-vault/files": { "post": { "description": "Server-to-server only. Authenticate the registered confidential application using HTTP Basic, and supply the owner's current Hybrid ID OAuth access_token. The owner must explicitly approve vault:files:upload and/or vault:files:read. prepare-upload allocates a stable file ID before local encryption. register binds its immutable encrypted manifest, put-chunk sends a ciphertext chunk, commit verifies completion, read/read-chunk retrieve ciphertext. list exposes only files created through this exact application and owner connection. Request context and vault IDs are derived by Hybrid ID; never send a password, private key, general account credential or caller-selected vault. Revocation and session expiry are checked on every request. Exact encrypted retries reuse the original request/file identifiers. refresh-connection renews a separately approved owner/API file connection using only its app-scoped renewal capability and current confidential app authentication; native credentials are never sent to the partner. It cannot renew expired/revoked native authority, consent or grants. request-decryption asks for separate owner approval of this exact file, recipient key, purpose and expiry; decryption-status reports the decision and releases a wrapped file key only while approved. OAuth read consent does not itself permit backend decryption. Revocation, expiry, recipient rotation and changed owner consent stop future file retrieval; already decrypted information cannot be recalled. No wallet or spending authority is granted.", "operationId": "files", "parameters": [ { "description": "Optional caller correlation identifier. The gateway emits the effective value on the response.", "in": "header", "name": "X-Request-ID", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerVaultRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "Validated encrypted storage receipt or application-scoped inventory" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The request syntax, required metadata, or JSON body is malformed." }, "401": { "content": { "application/json": { "example": { "code": "invalid_credentials", "message": "The bearer credential is missing, expired, or invalid." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Application authentication or owner session expired." }, "403": { "content": { "application/json": { "example": { "code": "insufficient_scope", "message": "The principal lacks owner-scoped Data Vault read authority." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Current owner consent or authority is missing." }, "404": { "content": { "application/json": { "example": { "code": "data_vault_object_not_found", "message": "The object does not exist in the authenticated workspace." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "File is unavailable to this app and owner." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Upload state or immutable retry changed." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Ciphertext transport size exceeded." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "The caller exceeded an enforced request or resource limit." }, "503": { "content": { "application/json": { "example": { "code": "data_vault_unavailable", "message": "Authoritative Data Vault metadata is temporarily unavailable." }, "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Storage or identity authority unavailable." } }, "security": [ { "partner_client_basic": [] } ], "summary": "DATA: Use owner-approved application encrypted files", "tags": [ "Data Vault" ], "x-hybrid-chain": { "agentRequestProfile": null, "applications": [ "Data Vault" ], "authoritativeOwners": [ "vault-service" ], "errors": [ { "code": "invalid_credentials", "description": "The bearer credential is missing, expired, or invalid.", "status": 401 }, { "code": "insufficient_scope", "description": "The principal lacks owner-scoped Data Vault read authority.", "status": 403 }, { "code": "data_vault_object_not_found", "description": "The object does not exist in the authenticated workspace.", "status": 404 }, { "code": "invalid_data_vault_object", "description": "The object identifier is invalid.", "status": 422 }, { "code": "data_vault_request_rejected", "description": "Owner or workspace policy rejected the Data Vault request.", "status": 422 }, { "code": "data_vault_unavailable", "description": "Authoritative Data Vault metadata is temporarily unavailable.", "status": 503 } ], "idempotencyKeyRequired": false, "implementationStatus": "implemented-contract", "registryOperationId": "post-api-v2-data-vault-files", "requestSignatureComponents": null, "requestSignatureRequired": false, "requiredScope": "vault:files:upload or vault:files:read, operation dependent", "requiredScopes": [ "vault:files:upload or vault:files:read, operation dependent" ], "requiredScopesByNetwork": null, "runtimeSources": [ { "catalog": "gateway", "method": "POST", "path": "/api/v2/data-vault/files" } ] } } } }, "components": { "securitySchemes": { "partner_client_basic": { "description": "Registered confidential application credentials. The owner-consented OAuth access_token is supplied in the JSON request.", "scheme": "basic", "type": "http" } }, "schemas": { "PartnerVaultRequest": { "oneOf": [ { "properties": { "operation": { "enum": [ "refresh-connection" ], "type": "string" }, "refresh_token": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "refresh_token", "request_id", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "expires_at": { "format": "int64", "minimum": 0, "type": "integer" }, "object_id": { "type": "string" }, "operation": { "enum": [ "request-decryption" ], "type": "string" }, "purpose": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "access_token", "object_id", "request_id", "purpose", "expires_at", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "object_id": { "type": "string" }, "operation": { "enum": [ "decryption-status" ], "type": "string" }, "request_id": { "type": "string" } }, "required": [ "access_token", "object_id", "request_id", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "operation": { "enum": [ "context" ], "type": "string" } }, "required": [ "access_token", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "after": { "type": [ "string", "null" ] }, "operation": { "enum": [ "list" ], "type": "string" } }, "required": [ "access_token", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "operation": { "enum": [ "prepare-upload" ], "type": "string" }, "request_id": { "type": "string" } }, "required": [ "access_token", "request_id", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "object_id": { "type": "string" }, "operation": { "enum": [ "register" ], "type": "string" }, "registration": {} }, "required": [ "access_token", "object_id", "registration", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "ciphertext": { "type": "string" }, "index": { "format": "int32", "minimum": 0, "type": "integer" }, "object_id": { "type": "string" }, "operation": { "enum": [ "put-chunk" ], "type": "string" } }, "required": [ "access_token", "object_id", "index", "ciphertext", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "object_id": { "type": "string" }, "operation": { "enum": [ "commit" ], "type": "string" } }, "required": [ "access_token", "object_id", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "object_id": { "type": "string" }, "operation": { "enum": [ "cancel" ], "type": "string" }, "registration": {} }, "required": [ "access_token", "object_id", "registration", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "object_id": { "type": "string" }, "operation": { "enum": [ "proof" ], "type": "string" } }, "required": [ "access_token", "object_id", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "object_id": { "type": "string" }, "operation": { "enum": [ "read" ], "type": "string" } }, "required": [ "access_token", "object_id", "operation" ], "type": "object" }, { "properties": { "access_token": { "type": "string" }, "index": { "format": "int32", "minimum": 0, "type": "integer" }, "object_id": { "type": "string" }, "operation": { "enum": [ "read-chunk" ], "type": "string" } }, "required": [ "access_token", "object_id", "index", "operation" ], "type": "object" } ] }, "ErrorResponse": { "description": "Standard safe V2 error envelope. Agents must branch on code and may display message.", "properties": { "code": { "description": "Stable machine-readable error code. Branch on this value instead of parsing `message`.", "example": "invalid_credentials", "type": "string" }, "message": { "description": "Human-readable diagnostic safe to display or retain. Wording may become more specific over time.", "example": "the supplied Hybrid credential is invalid", "type": "string" } }, "required": [ "code", "message" ], "type": "object" } } } }