{ "openapi": "3.1.0", "info": { "title": "vBase API", "version": "v1", "description": "[vBase Documentation](https://docs.vbase.com/)" }, "paths": { "/api/v1/collections": { "get": { "operationId": "collections_list", "description": "Get user collections with optional filtering", "parameters": [ { "in": "query", "name": "is_pinned", "schema": { "type": "boolean" }, "description": "Filter by pinned status" }, { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 }, "description": "Opt-in page size (1-1000). When set, the response carries X-Total-Count and, if more results exist, a Link rel=next header." }, { "in": "query", "name": "offset", "schema": { "type": "integer", "minimum": 0 }, "description": "Number of collections to skip; requires limit" }, { "in": "query", "name": "user_address", "schema": { "type": "string" }, "description": "Filter by user address" } ], "tags": [ "Collections" ], "security": [ { "Bearer": [] } ], "responses": { "200": { "headers": { "X-Total-Count": { "schema": { "type": "integer" }, "description": "Unpaged collection count; sent with limit" }, "Link": { "schema": { "type": "string" }, "description": "Relative next-page URL with rel=\"next\"; sent with limit" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } }, "examples": { "CollectionList": { "value": [ { "id": 1, "name": "my-collection", "cid": "0xabababababababababababababababababababababababababababababababab", "is_pinned": false, "is_portfolio": false, "is_portfolio_collection": false, "is_public": false, "created_at": "2025-07-23T11:42:15+00:00", "description": "Example collection" } ], "summary": "Collection list" } } } }, "description": "Collections retrieved successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad request - invalid query parameters" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "User not found" } } }, "post": { "operationId": "collections_create", "description": "Create a new user collection", "tags": [ "Collections" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreateModelRequest" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CollectionCreateModelRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CollectionCreateModelRequest" } } }, "required": true }, "security": [ { "Bearer": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } }, "description": "Collection created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad request - validation error" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Conflict - collection already exists" } } } }, "/api/v1/collections/verify": { "post": { "operationId": "collections_verify_create", "description": "\nVerify a collection of stamped objects against the blockchain.\n\nUse the request `Content-Type` to choose the payload format:\n\n**Raw JSON body**\n```json\n{\n \"collection_name\": \"my-collection\",\n \"user_address\": \"0x123...\",\n \"objects\": [\n {\n \"cid\": \"cid1\",\n \"timestamp\": \"2024-01-01T00:00:00+00:00\"\n }\n ]\n}\n```\n\n**Raw CSV body**\nSend the CSV string directly with `Content-Type: text/csv`, for example:\n\n```csv\ncollection_name,user_address\nvb-test,0x4A281DdC750359d5C0D2D51A890cefA43485EF2d\nt,c,f\n2025-07-23 11:42:15+00:00,0x6f3328cba0ffde8429e66008708419751921bf41737e32a0fcd173849e325561,application-logs2025-07-15T19_46_13.098Z-2025-07-16T19_46_13.098Z_2025-07-23_11-42-15+0000.json\n2025-07-23 20:34:58+00:00,0xaeda4cf7d65f9d67b128bf795b5f237183550a814c9d4aa83c7e84f027d4aeec,attribcache140_2025-07-23_20-34-58+0000.bin\n```\n\n`collection_name` and `user_address` are optional in JSON requests. When\nomitted, the backend will try to infer metadata from the payload.\n\nFor CSV requests, the leading metadata section\n`collection_name,user_address` is optional.\n\n**Multipart/form-data (legacy)**\nUpload a `.csv` or `.json` file in the `file` field. The payload is normalized\nto the same validated API model as raw JSON and raw CSV requests.\n\n`Accept` controls the response type. This endpoint currently returns JSON.\n ", "summary": "Verify a user collection against the blockchain", "tags": [ "Collections" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyUserCollectionRequestSchemaRequest" } }, "text/csv": { "schema": { "type": "string", "description": "Raw CSV with an optional leading collection metadata section." } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Collection payload in a .csv or .json file." } } } } }, "required": true }, "security": [ { "Bearer": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCollectionResponse" }, "examples": { "CollectionVerification": { "value": { "display_timezone": "UTC", "collections": [ { "name": "my-collection", "cid": "0x329c036f2bcedbb9c44521c22a84d82ae328fef03e942c42b447d4ae67bbd800", "user_address": "0x4A281DdC750359d5C0D2D51A890cefA43485EF2d", "matched_receipts": [ { "transaction_hash": "0xbe3f57e7ad7b00e79f88b3f9ffc9fdee84d3251cfc2d121386d8fe793b0d782a", "user_address": "0x4A281DdC750359d5C0D2D51A890cefA43485EF2d", "set_cid": "0x329c036f2bcedbb9c44521c22a84d82ae328fef03e942c42b447d4ae67bbd800", "object_cid": "0x6f3328cba0ffde8429e66008708419751921bf41737e32a0fcd173849e325561", "timestamp": "2025-07-23T11:42:15+00:00", "chain_id": 8453 } ], "unmatched_objects": [ { "cid": "0xaeda4cf7d65f9d67b128bf795b5f237183550a814c9d4aa83c7e84f027d4aeec", "timestamp": "2025-07-23T20:34:58+00:00" } ], "unmatched_receipts": [] } ] }, "summary": "Collection verification" } } } }, "description": "Verification result" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid input data" } } } }, "/api/v1/stamp/": { "post": { "operationId": "stamp_create", "description": "\n **DEPRECATED**: This endpoint is deprecated. Please use `/api/v1/stamps` instead.\n\n This endpoint allows users to stamp a file, inline data, or an existing CID.\n Accepts file, inline data, or CID and returns a stamp record with metadata.\n Exactly one of 'file', 'data', or 'data_cid' must be provided.\n\n Send multipart/form-data or application/x-www-form-urlencoded fields,\n or an application/json object with the same field names. File uploads\n require multipart/form-data; in JSON, 'data' must be a string.\n\n Collection can be specified using either:\n - collection_cid: Direct CID of the collection\n - collection_name: Name of the collection (case-insensitive, will be converted to CID)\n\n Only one collection parameter can be specified.\n\n For 'data' parameter, you can optionally specify 'file_name' to customize the file name\n instead of using the auto-generated name based on CID.\n ", "summary": "[DEPRECATED] Stamp a file, inline data, or CID", "tags": [ "Stamps" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": false, "description": "Provide exactly one of file, nonempty data, or nonempty data_cid. Use at most one nonempty collection selector. CamelCase aliases are accepted for compatibility; do not send both spellings of one field.", "properties": { "file": { "type": "string", "format": "binary", "description": "Binary upload; a named file may contain zero bytes. An empty text multipart field is instead an unselected placeholder. JSON Schema cannot distinguish those parts when both are represented as file=''." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data", "description": "Inline text, including serialized JSON. An empty string does not select data.", "examples": [ "{\"hello\": \"world\"}" ] }, "data_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Data Cid" }, "collection_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "store_stamped_file": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Store Stamped File" }, "idempotent": { "default": false, "title": "Idempotent", "type": "boolean" }, "idempotency_window": { "default": 3600, "title": "Idempotency Window", "type": "integer" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "dataCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Data Cid", "description": "Compatibility alias for data_cid." }, "collectionCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Collection Cid", "description": "Compatibility alias for collection_cid." }, "collectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Name", "description": "Compatibility alias for collection_name." }, "storeStampedFile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store Stamped File", "description": "Compatibility alias for store_stamped_file." }, "idempotencyWindow": { "title": "Idempotency Window", "type": "integer", "description": "Compatibility alias for idempotency_window." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Compatibility alias for file_name." } }, "title": "StampRequestModel", "type": "object", "allOf": [ { "not": { "required": [ "data_cid", "dataCid" ] } }, { "not": { "required": [ "collection_cid", "collectionCid" ] } }, { "not": { "required": [ "collection_name", "collectionName" ] } }, { "not": { "required": [ "store_stamped_file", "storeStampedFile" ] } }, { "not": { "required": [ "idempotency_window", "idempotencyWindow" ] } }, { "not": { "required": [ "file_name", "fileName" ] } }, { "not": { "allOf": [ { "anyOf": [ { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionCid" ], "properties": { "collectionCid": { "type": "string", "minLength": 1 } } } ] }, { "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionName" ], "properties": { "collectionName": { "type": "string", "minLength": 1 } } } ] } ] } } ], "oneOf": [ { "title": "File upload", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Binary upload; a named file may contain zero bytes. An empty text multipart field is instead an unselected placeholder. JSON Schema cannot distinguish those parts when both are represented as file=''." } }, "not": { "anyOf": [ { "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 } } }, { "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ] } ] } }, { "title": "Inline data", "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 }, "file": { "type": "string", "enum": [ "" ] } } }, { "title": "Content CID", "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ], "properties": { "file": { "type": "string", "enum": [ "" ] } } } ] }, "examples": { "InlineText": { "value": { "data": "hello" }, "summary": "Inline text" }, "ExistingCID": { "value": { "data_cid": "0xabababababababababababababababababababababababababababababababab" }, "summary": "Existing CID" }, "FileUpload": { "value": { "file": "(binary)" }, "summary": "File upload" } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "description": "Provide exactly one of file, nonempty data, or nonempty data_cid. Use at most one nonempty collection selector. CamelCase aliases are accepted for compatibility; do not send both spellings of one field.", "properties": { "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data", "description": "Inline text, including serialized JSON. An empty string does not select data.", "examples": [ "{\"hello\": \"world\"}" ] }, "data_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Data Cid" }, "collection_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "store_stamped_file": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Store Stamped File" }, "idempotent": { "default": false, "title": "Idempotent", "type": "boolean" }, "idempotency_window": { "default": 3600, "title": "Idempotency Window", "type": "integer" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "dataCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Data Cid", "description": "Compatibility alias for data_cid." }, "collectionCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Collection Cid", "description": "Compatibility alias for collection_cid." }, "collectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Name", "description": "Compatibility alias for collection_name." }, "storeStampedFile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store Stamped File", "description": "Compatibility alias for store_stamped_file." }, "idempotencyWindow": { "title": "Idempotency Window", "type": "integer", "description": "Compatibility alias for idempotency_window." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Compatibility alias for file_name." } }, "title": "StampRequestModel", "type": "object", "allOf": [ { "not": { "required": [ "data_cid", "dataCid" ] } }, { "not": { "required": [ "collection_cid", "collectionCid" ] } }, { "not": { "required": [ "collection_name", "collectionName" ] } }, { "not": { "required": [ "store_stamped_file", "storeStampedFile" ] } }, { "not": { "required": [ "idempotency_window", "idempotencyWindow" ] } }, { "not": { "required": [ "file_name", "fileName" ] } }, { "not": { "allOf": [ { "anyOf": [ { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionCid" ], "properties": { "collectionCid": { "type": "string", "minLength": 1 } } } ] }, { "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionName" ], "properties": { "collectionName": { "type": "string", "minLength": 1 } } } ] } ] } } ], "oneOf": [ { "title": "Inline data", "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 } } }, { "title": "Content CID", "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ] } ] }, "examples": { "InlineText": { "value": { "data": "hello" }, "summary": "Inline text" }, "ExistingCID": { "value": { "data_cid": "0xabababababababababababababababababababababababababababababababab" }, "summary": "Existing CID" } } }, "application/json": { "schema": { "additionalProperties": false, "description": "Provide exactly one of file, nonempty data, or nonempty data_cid. Use at most one nonempty collection selector. CamelCase aliases are accepted for compatibility; do not send both spellings of one field.", "properties": { "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data", "description": "Inline text, including serialized JSON. An empty string does not select data.", "examples": [ "{\"hello\": \"world\"}" ] }, "data_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Data Cid" }, "collection_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "store_stamped_file": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Store Stamped File" }, "idempotent": { "default": false, "title": "Idempotent", "type": "boolean" }, "idempotency_window": { "default": 3600, "title": "Idempotency Window", "type": "integer" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "dataCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Data Cid", "description": "Compatibility alias for data_cid." }, "collectionCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Collection Cid", "description": "Compatibility alias for collection_cid." }, "collectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Name", "description": "Compatibility alias for collection_name." }, "storeStampedFile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store Stamped File", "description": "Compatibility alias for store_stamped_file." }, "idempotencyWindow": { "title": "Idempotency Window", "type": "integer", "description": "Compatibility alias for idempotency_window." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Compatibility alias for file_name." } }, "title": "StampRequestModel", "type": "object", "allOf": [ { "not": { "required": [ "data_cid", "dataCid" ] } }, { "not": { "required": [ "collection_cid", "collectionCid" ] } }, { "not": { "required": [ "collection_name", "collectionName" ] } }, { "not": { "required": [ "store_stamped_file", "storeStampedFile" ] } }, { "not": { "required": [ "idempotency_window", "idempotencyWindow" ] } }, { "not": { "required": [ "file_name", "fileName" ] } }, { "not": { "allOf": [ { "anyOf": [ { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionCid" ], "properties": { "collectionCid": { "type": "string", "minLength": 1 } } } ] }, { "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionName" ], "properties": { "collectionName": { "type": "string", "minLength": 1 } } } ] } ] } } ], "oneOf": [ { "title": "Inline data", "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 } } }, { "title": "Content CID", "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ] } ] }, "examples": { "InlineText": { "value": { "data": "hello" }, "summary": "Inline text" }, "ExistingCID": { "value": { "data_cid": "0xabababababababababababababababababababababababababababababababab" }, "summary": "Existing CID" } } } }, "required": true }, "security": [ { "Bearer": [] } ], "deprecated": true, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotentStampResponse" } } }, "description": "Idempotent request - returning previous stamp." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCreatedResponse" } } }, "description": "Stamp created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad request - invalid input or idempotent conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal server error" } }, "x-code-samples": [ { "lang": "shell", "source": "curl --request POST \"${VBASE_API_URL:-https://app.vbase.com}/api/v1/stamp/\" \\\n --header \"Authorization: Bearer $VBASE_API_KEY\" \\\n --form-string 'data=hello'" } ] } }, "/api/v1/stamps": { "post": { "operationId": "stamps_create", "description": "\n This endpoint allows users to stamp a file, inline data, or an existing CID.\n Accepts file, inline data, or CID and returns a stamp record with metadata.\n Exactly one of 'file', 'data', or 'data_cid' must be provided.\n\n Send multipart/form-data or application/x-www-form-urlencoded fields,\n or an application/json object with the same field names. File uploads\n require multipart/form-data; in JSON, 'data' must be a string.\n\n Collection can be specified using either:\n - collection_cid: Direct CID of the collection\n - collection_name: Name of the collection (case-insensitive, will be converted to CID)\n\n Only one collection parameter can be specified.\n\n For 'data' parameter, you can optionally specify 'file_name' to customize the file name\n instead of using the auto-generated name based on CID.\n ", "summary": "Stamp a file, inline data, or CID", "tags": [ "Stamps" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": false, "description": "Provide exactly one of file, nonempty data, or nonempty data_cid. Use at most one nonempty collection selector. CamelCase aliases are accepted for compatibility; do not send both spellings of one field.", "properties": { "file": { "type": "string", "format": "binary", "description": "Binary upload; a named file may contain zero bytes. An empty text multipart field is instead an unselected placeholder. JSON Schema cannot distinguish those parts when both are represented as file=''." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data", "description": "Inline text, including serialized JSON. An empty string does not select data.", "examples": [ "{\"hello\": \"world\"}" ] }, "data_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Data Cid" }, "collection_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "store_stamped_file": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Store Stamped File" }, "idempotent": { "default": false, "title": "Idempotent", "type": "boolean" }, "idempotency_window": { "default": 3600, "title": "Idempotency Window", "type": "integer" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "dataCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Data Cid", "description": "Compatibility alias for data_cid." }, "collectionCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Collection Cid", "description": "Compatibility alias for collection_cid." }, "collectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Name", "description": "Compatibility alias for collection_name." }, "storeStampedFile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store Stamped File", "description": "Compatibility alias for store_stamped_file." }, "idempotencyWindow": { "title": "Idempotency Window", "type": "integer", "description": "Compatibility alias for idempotency_window." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Compatibility alias for file_name." } }, "title": "StampRequestModel", "type": "object", "allOf": [ { "not": { "required": [ "data_cid", "dataCid" ] } }, { "not": { "required": [ "collection_cid", "collectionCid" ] } }, { "not": { "required": [ "collection_name", "collectionName" ] } }, { "not": { "required": [ "store_stamped_file", "storeStampedFile" ] } }, { "not": { "required": [ "idempotency_window", "idempotencyWindow" ] } }, { "not": { "required": [ "file_name", "fileName" ] } }, { "not": { "allOf": [ { "anyOf": [ { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionCid" ], "properties": { "collectionCid": { "type": "string", "minLength": 1 } } } ] }, { "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionName" ], "properties": { "collectionName": { "type": "string", "minLength": 1 } } } ] } ] } } ], "oneOf": [ { "title": "File upload", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Binary upload; a named file may contain zero bytes. An empty text multipart field is instead an unselected placeholder. JSON Schema cannot distinguish those parts when both are represented as file=''." } }, "not": { "anyOf": [ { "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 } } }, { "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ] } ] } }, { "title": "Inline data", "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 }, "file": { "type": "string", "enum": [ "" ] } } }, { "title": "Content CID", "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ], "properties": { "file": { "type": "string", "enum": [ "" ] } } } ] }, "examples": { "InlineText": { "value": { "data": "hello" }, "summary": "Inline text" }, "ExistingCID": { "value": { "data_cid": "0xabababababababababababababababababababababababababababababababab" }, "summary": "Existing CID" }, "FileUpload": { "value": { "file": "(binary)" }, "summary": "File upload" } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "description": "Provide exactly one of file, nonempty data, or nonempty data_cid. Use at most one nonempty collection selector. CamelCase aliases are accepted for compatibility; do not send both spellings of one field.", "properties": { "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data", "description": "Inline text, including serialized JSON. An empty string does not select data.", "examples": [ "{\"hello\": \"world\"}" ] }, "data_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Data Cid" }, "collection_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "store_stamped_file": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Store Stamped File" }, "idempotent": { "default": false, "title": "Idempotent", "type": "boolean" }, "idempotency_window": { "default": 3600, "title": "Idempotency Window", "type": "integer" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "dataCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Data Cid", "description": "Compatibility alias for data_cid." }, "collectionCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Collection Cid", "description": "Compatibility alias for collection_cid." }, "collectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Name", "description": "Compatibility alias for collection_name." }, "storeStampedFile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store Stamped File", "description": "Compatibility alias for store_stamped_file." }, "idempotencyWindow": { "title": "Idempotency Window", "type": "integer", "description": "Compatibility alias for idempotency_window." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Compatibility alias for file_name." } }, "title": "StampRequestModel", "type": "object", "allOf": [ { "not": { "required": [ "data_cid", "dataCid" ] } }, { "not": { "required": [ "collection_cid", "collectionCid" ] } }, { "not": { "required": [ "collection_name", "collectionName" ] } }, { "not": { "required": [ "store_stamped_file", "storeStampedFile" ] } }, { "not": { "required": [ "idempotency_window", "idempotencyWindow" ] } }, { "not": { "required": [ "file_name", "fileName" ] } }, { "not": { "allOf": [ { "anyOf": [ { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionCid" ], "properties": { "collectionCid": { "type": "string", "minLength": 1 } } } ] }, { "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionName" ], "properties": { "collectionName": { "type": "string", "minLength": 1 } } } ] } ] } } ], "oneOf": [ { "title": "Inline data", "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 } } }, { "title": "Content CID", "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ] } ] }, "examples": { "InlineText": { "value": { "data": "hello" }, "summary": "Inline text" }, "ExistingCID": { "value": { "data_cid": "0xabababababababababababababababababababababababababababababababab" }, "summary": "Existing CID" } } }, "application/json": { "schema": { "additionalProperties": false, "description": "Provide exactly one of file, nonempty data, or nonempty data_cid. Use at most one nonempty collection selector. CamelCase aliases are accepted for compatibility; do not send both spellings of one field.", "properties": { "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data", "description": "Inline text, including serialized JSON. An empty string does not select data.", "examples": [ "{\"hello\": \"world\"}" ] }, "data_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Data Cid" }, "collection_cid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "store_stamped_file": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": null, "title": "Store Stamped File" }, "idempotent": { "default": false, "title": "Idempotent", "type": "boolean" }, "idempotency_window": { "default": 3600, "title": "Idempotency Window", "type": "integer" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" }, "dataCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Data Cid", "description": "Compatibility alias for data_cid." }, "collectionCid": { "anyOf": [ { "type": "string", "enum": [ "" ] }, { "type": "string", "pattern": "^0x[0-9a-fA-F]{64}$", "minLength": 66, "maxLength": 66 }, { "type": "null" } ], "title": "Collection Cid", "description": "Compatibility alias for collection_cid." }, "collectionName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Collection Name", "description": "Compatibility alias for collection_name." }, "storeStampedFile": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Store Stamped File", "description": "Compatibility alias for store_stamped_file." }, "idempotencyWindow": { "title": "Idempotency Window", "type": "integer", "description": "Compatibility alias for idempotency_window." }, "fileName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "File Name", "description": "Compatibility alias for file_name." } }, "title": "StampRequestModel", "type": "object", "allOf": [ { "not": { "required": [ "data_cid", "dataCid" ] } }, { "not": { "required": [ "collection_cid", "collectionCid" ] } }, { "not": { "required": [ "collection_name", "collectionName" ] } }, { "not": { "required": [ "store_stamped_file", "storeStampedFile" ] } }, { "not": { "required": [ "idempotency_window", "idempotencyWindow" ] } }, { "not": { "required": [ "file_name", "fileName" ] } }, { "not": { "allOf": [ { "anyOf": [ { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionCid" ], "properties": { "collectionCid": { "type": "string", "minLength": 1 } } } ] }, { "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collectionName" ], "properties": { "collectionName": { "type": "string", "minLength": 1 } } } ] } ] } } ], "oneOf": [ { "title": "Inline data", "required": [ "data" ], "properties": { "data": { "type": "string", "minLength": 1 } } }, { "title": "Content CID", "anyOf": [ { "required": [ "data_cid" ], "properties": { "data_cid": { "type": "string", "minLength": 1 } } }, { "required": [ "dataCid" ], "properties": { "dataCid": { "type": "string", "minLength": 1 } } } ] } ] }, "examples": { "InlineText": { "value": { "data": "hello" }, "summary": "Inline text" }, "ExistingCID": { "value": { "data_cid": "0xabababababababababababababababababababababababababababababababab" }, "summary": "Existing CID" } } } }, "required": true }, "security": [ { "Bearer": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotentStampResponse" } } }, "description": "Idempotent request - returning previous stamp." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCreatedResponse" } } }, "description": "Stamp created successfully" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Bad request - invalid input or idempotent conflict" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Internal server error" } }, "x-code-samples": [ { "lang": "shell", "source": "curl --request POST \"${VBASE_API_URL:-https://app.vbase.com}/api/v1/stamps\" \\\n --header \"Authorization: Bearer $VBASE_API_KEY\" \\\n --form-string 'data=hello'" } ] } }, "/api/v1/stamps/certificate": { "post": { "operationId": "stamps_certificate_create", "description": "Resolve the exact receipt and return generated PDF bytes directly.", "summary": "Download a stamp certificate PDF (public)", "tags": [ "Stamps" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateSelectorRequest" }, "examples": { "ReceiptSelectors": { "value": { "object_cid": "0xabababababababababababababababababababababababababababababababab", "transaction_hash": "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd", "chain_id": 8453 }, "summary": "Receipt selectors", "description": "Replace these selectors with values from an existing receipt." } } } }, "required": true }, "responses": { "200": { "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } }, "description": "PDF attachment" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid selectors" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Stamp not found" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Ambiguous stamp" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Certificate temporarily unavailable" } } } }, "/api/v1/stamps/upload-stamped-file": { "post": { "operationId": "stamps_upload-stamped-file_create", "description": "\n This endpoint allows users to upload a file or inline data that has been\n previously stamped.\n It validates that a matching commitment exists in the blockchain records for the\n authenticated user and specified collection.\n\n The collection can be specified using either:\n - collection_name: Name of the collection (case-insensitive)\n - collection_cid: CID of the collection\n\n At least one of 'collection_name' or 'collection_cid' must be provided.\n If both are provided, the stored CID for the named collection must match\n the provided collection_cid.\n The content can be provided as either 'file' or 'data', but not both.\n 'file_name' is required whenever 'data' is provided.\n\n Send multipart/form-data or application/x-www-form-urlencoded fields,\n or an application/json object with the same field names. File uploads\n require multipart/form-data; in JSON, 'data' must be a string.\n\n The endpoint performs the following validations:\n - Ensures at least one collection identifier is provided.\n - Ensures exactly one of `file` or `data` is provided.\n - Ensures `file_name` is provided when `data` is used.\n - Finds the collection for the authenticated user.\n - Calculates the object CID from the uploaded file, or from inline data\n when no file is provided.\n - Verifies that matching commitments exist in blockchain records for the\n user's address and collection.\n - Uploads the file and associates it with each matching commitment.\n - Returns the existing file object with HTTP 200 when the matching\n commitment is already associated with a file.\n\n Note: User address is automatically determined from the authenticated user's profile.\n\n Returns structured error responses with appropriate HTTP status codes:\n - 400: Invalid input or validation failed, or collection_cid does not match collection_name\n - 404: Collection not found or no blockchain records found\n - 500: File processing, blockchain, or upload errors\n ", "summary": "Upload a stamped file", "tags": [ "Stamps" ], "requestBody": { "content": { "multipart/form-data": { "schema": { "additionalProperties": false, "description": "Pydantic model for validating upload stamped request parameters.", "properties": { "collection_name": { "type": [ "string", "null" ], "description": "Collection name (case-insensitive)" }, "collection_cid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Collection CID", "title": "Collection Cid" }, "file": { "type": "string", "format": "binary", "description": "Previously stamped binary file, including a zero-byte file. An empty text multipart field is an unselected placeholder alongside inline data. JSON Schema cannot distinguish those parts when both are represented as file=''." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" } }, "title": "UploadStampedFileRequestModel", "type": "object", "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } } ], "oneOf": [ { "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "Previously stamped binary file, including a zero-byte file. An empty text multipart field is an unselected placeholder alongside inline data. JSON Schema cannot distinguish those parts when both are represented as file=''." }, "data": { "enum": [ null, "" ] } } }, { "required": [ "data", "file_name" ], "properties": { "data": { "type": "string", "minLength": 1 }, "file_name": { "type": "string", "minLength": 1 }, "file": { "type": "string", "enum": [ "" ] } } } ] }, "examples": { "PreviouslyStampedInlineData": { "value": { "collection_name": "my-collection", "data": "hello", "file_name": "example.txt" }, "summary": "Previously stamped inline data" } } }, "application/x-www-form-urlencoded": { "schema": { "additionalProperties": false, "description": "Pydantic model for validating upload stamped request parameters.", "properties": { "collection_name": { "type": [ "string", "null" ], "description": "Collection name (case-insensitive)" }, "collection_cid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Collection CID", "title": "Collection Cid" }, "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" } }, "title": "UploadStampedFileRequestModel", "type": "object", "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } } ], "oneOf": [ { "required": [ "data", "file_name" ], "properties": { "data": { "type": "string", "minLength": 1 }, "file_name": { "type": "string", "minLength": 1 }, "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." } } } ] }, "examples": { "PreviouslyStampedInlineData": { "value": { "collection_name": "my-collection", "data": "hello", "file_name": "example.txt" }, "summary": "Previously stamped inline data" } } }, "application/json": { "schema": { "additionalProperties": false, "description": "Pydantic model for validating upload stamped request parameters.", "properties": { "collection_name": { "type": [ "string", "null" ], "description": "Collection name (case-insensitive)" }, "collection_cid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "description": "Collection CID", "title": "Collection Cid" }, "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." }, "data": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Data" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" } }, "title": "UploadStampedFileRequestModel", "type": "object", "anyOf": [ { "required": [ "collection_name" ], "properties": { "collection_name": { "type": "string", "minLength": 1 } } }, { "required": [ "collection_cid" ], "properties": { "collection_cid": { "type": "string", "minLength": 1 } } } ], "oneOf": [ { "required": [ "data", "file_name" ], "properties": { "data": { "type": "string", "minLength": 1 }, "file_name": { "type": "string", "minLength": 1 }, "file": { "anyOf": [ { "type": "null" }, { "type": "string", "enum": [ "" ] } ], "description": "Empty or null unselected file placeholder only." } } } ] }, "examples": { "PreviouslyStampedInlineData": { "value": { "collection_name": "my-collection", "data": "hello", "file_name": "example.txt" }, "summary": "Previously stamped inline data" } } } }, "required": true }, "security": [ { "Bearer": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCreatedResponse" } } }, "description": "File was already uploaded for the matching commitment. Returns the existing file object." }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StampCreatedResponse" } } }, "description": "File uploaded and associated with matching commitment(s)" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid input or validation failed" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Collection not found or no blockchain records found" }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "File processing, blockchain, or upload errors" } }, "x-code-samples": [ { "lang": "shell", "source": "curl --request POST \"${VBASE_API_URL:-https://app.vbase.com}/api/v1/stamps/upload-stamped-file\" \\\n --header \"Authorization: Bearer $VBASE_API_KEY\" \\\n --form 'collection_name=my-collection' \\\n --form 'data=hello' \\\n --form 'file_name=example.txt'" } ] } }, "/api/v1/stamps/verify": { "post": { "operationId": "stamps_verify_create", "description": "\n This endpoint checks whether Content IDs (SHA3 hash) have previously been\n stamped on the blockchain using vBase. If a match is found, the api returns the full stamp details,\n including the timestamp, blockchain address, and other stamp details.\n ", "summary": "Verify one or more Content IDs (CIDs)", "tags": [ "Stamps" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerifyCIDModelRequest" } } }, "required": true }, "security": [ { "Bearer": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResult" }, "examples": { "VerifiedStamp": { "value": { "display_timezone": "UTC", "stamp_list": [ { "transaction_hash": "0xcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd", "user_address": "0x1212121212121212121212121212121212121212", "set_cid": "0xabababababababababababababababababababababababababababababababab", "object_cid": "0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef", "timestamp": "2025-07-23T11:42:15+00:00", "chain_id": 8453 } ] }, "summary": "Verified stamp" } } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid input data" } } } }, "/api/v1/users/{user_address}": { "get": { "operationId": "users_read", "description": "Return only display name, public address, and verified status.", "summary": "Get public user profile by address", "parameters": [ { "in": "path", "name": "user_address", "schema": { "type": "string" }, "required": true } ], "tags": [ "Users" ], "security": [ { "Bearer": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicUserProfile" }, "examples": { "PublicUserProfile": { "value": { "name": "Example User", "last_address": "0xabababababababababababababababababababab", "last_is_verified": true }, "summary": "Public user profile" } } } }, "description": "Public user profile" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Invalid user address" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "User not found" } } } }, "/api/v1/users/me": { "get": { "operationId": "users_me_list", "description": "Retrieve private account settings for the authenticated user.", "summary": "Get user account settings", "tags": [ "Users" ], "security": [ { "Bearer": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountSettings" }, "examples": { "AccountSettings": { "value": { "name": "Example User", "email": "user@example.com", "persistent_id": "vbase0123456789ab", "description": "Example account", "display_timezone": "UTC", "date_joined": "2025-07-23T11:42:15+00:00", "last_address": "0xabababababababababababababababababababab", "last_name": "Example User", "last_is_verified": true, "storage_type": "s3" }, "summary": "Account settings" } } } }, "description": "Account settings retrieved successfully" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "User not found" } } } } }, "components": { "schemas": { "AccountSettings": { "type": "object", "description": "Serializer for account settings response", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "persistent_id": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "display_timezone": { "type": [ "string", "null" ] }, "date_joined": { "type": [ "string", "null" ], "format": "date-time" }, "last_address": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "last_is_verified": { "type": [ "boolean", "null" ] }, "storage_type": { "type": [ "string", "null" ] } } }, "CertificateSelectorRequest": { "additionalProperties": false, "description": "Only receipt selectors are accepted from public callers.", "properties": { "object_cid": { "pattern": "^0x[0-9a-fA-F]{64}$", "title": "Object Cid", "type": "string" }, "transaction_hash": { "pattern": "^0x[0-9a-fA-F]{64}$", "title": "Transaction Hash", "type": "string" }, "chain_id": { "exclusiveMinimum": 0, "maximum": 9007199254740991, "title": "Chain Id", "type": "integer" }, "collection_cid": { "anyOf": [ { "pattern": "^0x[0-9a-fA-F]{64}$", "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Cid" } }, "required": [ "object_cid", "transaction_hash", "chain_id" ], "title": "CertificateSelector", "type": "object" }, "Collection": { "type": "object", "description": "Serializer for collections response", "properties": { "id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "cid": { "type": [ "string", "null" ] }, "is_pinned": { "type": [ "boolean", "null" ] }, "is_portfolio": { "type": [ "boolean", "null" ] }, "is_portfolio_collection": { "type": [ "boolean", "null" ] }, "is_public": { "type": [ "boolean", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ] } } }, "CollectionCreateModelRequest": { "additionalProperties": false, "description": "Pydantic model for validating collection creation request body.", "properties": { "name": { "title": "Name", "type": "string" }, "cid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Cid" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": "", "title": "Description" }, "is_pinned": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": true, "title": "Is Pinned" } }, "required": [ "name" ], "title": "CollectionCreateModel", "type": "object" }, "CommitmentReceipt": { "type": "object", "description": "Serializer for commitment receipt", "properties": { "transaction_hash": { "type": [ "string", "null" ] }, "user_address": { "type": [ "string", "null" ] }, "set_cid": { "type": [ "string", "null" ] }, "object_cid": { "type": [ "string", "null" ] }, "timestamp": { "type": [ "string", "null" ] }, "chain_id": { "type": [ "integer", "null" ] } } }, "Error": { "type": "object", "description": "Serializer for error responses", "properties": { "error": { "type": "string" }, "details": { "type": "string" } } }, "FileObject": { "type": "object", "description": "Serializer for file object in stamp response", "properties": { "file_name": { "type": [ "string", "null" ] }, "file_path": { "type": [ "string", "null" ] } } }, "IdempotentStampResponse": { "type": "object", "description": "Serializer for idempotent stamp response", "properties": { "commitment_receipt": { "oneOf": [ { "$ref": "#/components/schemas/CommitmentReceipt" }, { "type": "null" } ] } } }, "PublicUserProfile": { "type": "object", "description": "Public address lookup response contract.", "properties": { "name": { "type": [ "string", "null" ] }, "last_address": { "type": [ "string", "null" ] }, "last_is_verified": { "type": [ "boolean", "null" ] } } }, "StampCreatedResponse": { "type": "object", "description": "Serializer for created stamp response", "properties": { "commitment_receipt": { "oneOf": [ { "$ref": "#/components/schemas/CommitmentReceipt" }, { "type": "null" } ] }, "file_object": { "oneOf": [ { "$ref": "#/components/schemas/FileObject" }, { "type": "null" } ] } } }, "UnmatchedObject": { "type": "object", "description": "Serializer for an input object with no matching blockchain receipt", "properties": { "cid": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "cid", "timestamp" ] }, "UserCollectionObject": { "description": "A single stamped object in a user collection.", "properties": { "cid": { "title": "Cid", "type": "string" }, "timestamp": { "title": "Timestamp", "type": "string" }, "file_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "File Name" } }, "required": [ "cid", "timestamp" ], "title": "UserCollectionObject", "type": "object" }, "UserCollectionProcessingContext": { "description": "Processing context for a user collection verification request.", "properties": { "as_of_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "As Of Timestamp" }, "data_freshness_timestamp": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "default": null, "title": "Data Freshness Timestamp" } }, "title": "UserCollectionProcessingContext", "type": "object" }, "VerificationResult": { "type": "object", "description": "Serializer for stamp verification response", "properties": { "display_timezone": { "type": [ "string", "null" ] }, "stamp_list": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CommitmentReceipt" } } } }, "VerifyCIDModelRequest": { "additionalProperties": false, "description": "Pydantic model for validating query parameters.", "properties": { "cids": { "items": { "type": "string" }, "title": "Cids", "type": "array" }, "filter_by_user": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "default": false, "title": "Filter By User" } }, "required": [ "cids" ], "title": "VerifyCIDModel", "type": "object" }, "VerifyCollection": { "type": "object", "description": "Serializer for slim collection in verification responses", "properties": { "name": { "type": [ "string", "null" ] }, "cid": { "type": [ "string", "null" ] }, "user_address": { "type": [ "string", "null" ] }, "matched_receipts": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentReceipt" } }, "unmatched_objects": { "type": "array", "items": { "$ref": "#/components/schemas/UnmatchedObject" } }, "unmatched_receipts": { "type": "array", "items": { "$ref": "#/components/schemas/CommitmentReceipt" } } } }, "VerifyCollectionResponse": { "type": "object", "description": "Serializer for collection verification response", "properties": { "display_timezone": { "type": "string" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/VerifyCollection" } } } }, "VerifyUserCollectionRequestSchemaRequest": { "additionalProperties": false, "description": "Document the null context accepted by the request model's validator.", "properties": { "collection_cid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Cid" }, "collection_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "Collection Name" }, "user_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "default": null, "title": "User Address" }, "objects": { "items": { "$ref": "#/components/schemas/UserCollectionObject" }, "title": "Objects", "type": "array" }, "context": { "anyOf": [ { "$ref": "#/components/schemas/UserCollectionProcessingContext" }, { "type": "null" } ], "default": null } }, "title": "VerifyUserCollectionRequestSchema", "type": "object" } }, "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "description": "Enter your vBase API key. The key is opaque, not a JWT." } } }, "servers": [ { "url": "/" } ] }