{ "components": { "schemas": { "AllRequest": { "additionalProperties": false, "properties": { "include_metadata": { "default": false, "description": "Include receipt and signer metadata in each entry.", "type": "boolean" }, "limit": { "description": "Maximum number of entries to return in one page (1–200, default 50).", "format": "int32", "maximum": 200, "minimum": 1, "nullable": true, "type": "integer" }, "page_token": { "description": "Opaque pagination cursor from a previous `/v0/all/{predecessor_id}` response.", "nullable": true, "type": "string" } }, "type": "object" }, "ApiError": { "additionalProperties": false, "properties": { "error": { "type": "string" } }, "required": [ "error" ], "type": "object" }, "ByKeyRequest": { "additionalProperties": false, "properties": { "asc": { "default": false, "description": "Sort ascending for history results. Defaults to newest-first.", "type": "boolean" }, "include_metadata": { "default": false, "description": "Include receipt and signer metadata in each entry.", "type": "boolean" }, "key": { "description": "Exact key name to match across all accounts and predecessors.", "type": "string" }, "limit": { "description": "Maximum number of entries to return in one page (1–200, default 50).", "format": "int32", "maximum": 200, "minimum": 1, "nullable": true, "type": "integer" }, "page_token": { "description": "Opaque pagination cursor from a previous response for the same endpoint and filter set.", "nullable": true, "type": "string" } }, "required": [ "key" ], "type": "object" }, "KvEntry": { "additionalProperties": false, "properties": { "action_index": { "format": "uint32", "minimum": 0, "nullable": true, "type": "integer" }, "block_height": { "format": "uint64", "minimum": 0, "type": "integer" }, "block_timestamp": { "format": "uint64", "minimum": 0, "type": "integer" }, "current_account_id": { "type": "string" }, "key": { "type": "string" }, "predecessor_id": { "type": "string" }, "receipt_id": { "nullable": true, "type": "string" }, "signer_id": { "nullable": true, "type": "string" }, "tx_hash": { "nullable": true, "type": "string" }, "value": { "description": "Raw JSON value as stored in FastData." } }, "required": [ "predecessor_id", "current_account_id", "block_height", "block_timestamp", "key", "value" ], "type": "object" }, "LatestRequest": { "additionalProperties": false, "properties": { "include_metadata": { "default": false, "description": "Include receipt and signer metadata in each entry.", "type": "boolean" }, "key": { "description": "Exact key filter. Mutually exclusive with `key_prefix`.", "nullable": true, "type": "string" }, "key_prefix": { "description": "Prefix filter for matching key namespaces.", "nullable": true, "type": "string" }, "limit": { "description": "Maximum number of entries to return in one page (1–200, default 50).", "format": "int32", "maximum": 200, "minimum": 1, "nullable": true, "type": "integer" }, "page_token": { "description": "Opaque pagination cursor from a previous response for the same endpoint and filter set.", "nullable": true, "type": "string" } }, "type": "object" }, "ListResponse": { "additionalProperties": false, "properties": { "entries": { "items": { "$ref": "#/components/schemas/KvEntry" }, "type": "array" }, "page_token": { "description": "Opaque pagination cursor for the next page. Absent when there are no more results.", "nullable": true, "type": "string" } }, "required": [ "entries" ], "type": "object" }, "MultiRequest": { "additionalProperties": false, "properties": { "include_metadata": { "default": false, "description": "Include receipt and signer metadata in each entry.", "type": "boolean" }, "keys": { "description": "Fully qualified keys in current_account_id/predecessor_id/key form.", "items": { "type": "string" }, "maxItems": 100, "type": "array" } }, "required": [ "keys" ], "type": "object" }, "MultiResponse": { "additionalProperties": false, "properties": { "entries": { "items": { "oneOf": [ { "additionalProperties": false, "properties": { "action_index": { "format": "uint32", "minimum": 0, "nullable": true, "type": "integer" }, "block_height": { "format": "uint64", "minimum": 0, "type": "integer" }, "block_timestamp": { "format": "uint64", "minimum": 0, "type": "integer" }, "current_account_id": { "type": "string" }, "key": { "type": "string" }, "predecessor_id": { "type": "string" }, "receipt_id": { "nullable": true, "type": "string" }, "signer_id": { "nullable": true, "type": "string" }, "tx_hash": { "nullable": true, "type": "string" }, "value": { "description": "Raw JSON value as stored in FastData." } }, "required": [ "predecessor_id", "current_account_id", "block_height", "block_timestamp", "key", "value" ], "type": "object" }, { "enum": [ null ] } ] }, "type": "array" } }, "required": [ "entries" ], "type": "object" }, "QueryRequest": { "additionalProperties": false, "properties": { "asc": { "default": false, "description": "Sort ascending for history endpoints. Defaults to newest-first.", "type": "boolean" }, "include_metadata": { "default": false, "description": "Include receipt and signer metadata in each entry.", "type": "boolean" }, "key": { "description": "Exact key filter. Mutually exclusive with `key_prefix`.", "nullable": true, "type": "string" }, "key_prefix": { "description": "Prefix filter for matching key namespaces.", "nullable": true, "type": "string" }, "limit": { "description": "Maximum number of entries to return in one page (1–200, default 50).", "format": "int32", "maximum": 200, "minimum": 1, "nullable": true, "type": "integer" }, "page_token": { "description": "Opaque pagination cursor from a previous response for the same endpoint and filter set.", "nullable": true, "type": "string" } }, "type": "object" } } }, "info": { "description": "Read-only key-value queries over FastData records stored in ScyllaDB.", "title": "KV FastData API", "version": "3.0.3" }, "openapi": "3.0.3", "paths": { "/v0/all/{predecessor_id}": { "post": { "description": "Fetch the latest values for all contracts touched by one predecessor account.", "operationId": "all_by_predecessor", "parameters": [ { "description": "Calling account that wrote the FastData keys.", "example": "james.near", "in": "path", "name": "predecessor_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "include_metadata": true, "limit": 50 }, "schema": { "$ref": "#/components/schemas/AllRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Latest rows for the selected predecessor" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch latest key-value rows for one predecessor across all contracts", "tags": [ "latest" ], "x-fastnear-slug": "all_by_predecessor", "x-fastnear-title": "KV FastData API - All Latest Keys by Predecessor" } }, "/v0/history": { "post": { "description": "Fetch the historical values for a selected key across accounts and predecessors.", "operationId": "history_by_key", "requestBody": { "content": { "application/json": { "example": { "asc": true, "include_metadata": false, "key": "graph/follow/sleet.near", "limit": 50 }, "schema": { "$ref": "#/components/schemas/ByKeyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Historical rows for the selected key" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch historical rows by exact key across all indexed contracts", "tags": [ "history" ], "x-fastnear-slug": "history_by_key", "x-fastnear-title": "KV FastData API - History by Global Key" } }, "/v0/history/{current_account_id}": { "post": { "description": "Fetch historical FastData rows for one target account across all predecessor accounts.", "operationId": "history_by_account", "parameters": [ { "description": "Contract account whose FastData keys were written.", "example": "social.near", "in": "path", "name": "current_account_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "asc": false, "include_metadata": true, "key_prefix": "graph/follow/sleet.near", "limit": 50 }, "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Historical rows for the selected contract" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch historical key-value writes for one contract across all predecessors", "tags": [ "history" ], "x-fastnear-slug": "history_by_account", "x-fastnear-title": "KV FastData API - History by Account" } }, "/v0/history/{current_account_id}/{predecessor_id}": { "post": { "description": "Fetch historical FastData rows for a single predecessor and target account.", "operationId": "history_by_predecessor", "parameters": [ { "description": "Contract account whose FastData keys were written.", "example": "social.near", "in": "path", "name": "current_account_id", "required": true, "schema": { "type": "string" } }, { "description": "Calling account that wrote the FastData keys.", "example": "james.near", "in": "path", "name": "predecessor_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "asc": false, "include_metadata": true, "key_prefix": "graph/follow/", "limit": 50 }, "schema": { "$ref": "#/components/schemas/QueryRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Historical rows for the selected predecessor and account" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch historical key-value writes for one predecessor and contract", "tags": [ "history" ], "x-fastnear-slug": "history_by_predecessor", "x-fastnear-title": "KV FastData API - History by Predecessor" } }, "/v0/history/{current_account_id}/{predecessor_id}/{key}": { "get": { "description": "Fetch every historical write for one exact key under one predecessor and contract.", "operationId": "get_history_key", "parameters": [ { "description": "Contract account whose FastData keys were written.", "example": "social.near", "in": "path", "name": "current_account_id", "required": true, "schema": { "type": "string" } }, { "description": "Calling account that wrote the FastData keys.", "example": "james.near", "in": "path", "name": "predecessor_id", "required": true, "schema": { "type": "string" } }, { "description": "Exact FastData key to return.", "example": "graph/follow/sleet.near", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Historical rows for the selected predecessor, account, and key" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch historical rows for one exact key under one predecessor and contract", "tags": [ "history" ], "x-fastnear-slug": "get_history_key", "x-fastnear-title": "KV FastData API - History by Exact Key" } }, "/v0/latest/{current_account_id}": { "post": { "description": "Fetch the latest FastData rows for one target account across all predecessor accounts.", "operationId": "latest_by_account", "parameters": [ { "description": "Contract account whose FastData keys were written.", "example": "social.near", "in": "path", "name": "current_account_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "include_metadata": true, "key_prefix": "graph/follow/", "limit": 50 }, "schema": { "$ref": "#/components/schemas/LatestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Latest rows for the selected contract" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch latest key-value rows for one contract across all predecessors", "tags": [ "latest" ], "x-fastnear-slug": "latest_by_account", "x-fastnear-title": "KV FastData API - Latest by Account" } }, "/v0/latest/{current_account_id}/{predecessor_id}": { "post": { "description": "Fetch the latest FastData rows for a single predecessor and target account.", "operationId": "latest_by_predecessor", "parameters": [ { "description": "Contract account whose FastData keys were written.", "example": "social.near", "in": "path", "name": "current_account_id", "required": true, "schema": { "type": "string" } }, { "description": "Calling account that wrote the FastData keys.", "example": "james.near", "in": "path", "name": "predecessor_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "include_metadata": true, "key_prefix": "graph/follow/", "limit": 50 }, "schema": { "$ref": "#/components/schemas/LatestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Latest rows for the selected predecessor and account" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch latest key-value rows for one predecessor and contract", "tags": [ "latest" ], "x-fastnear-slug": "latest_by_predecessor", "x-fastnear-title": "KV FastData API - Latest by Predecessor" } }, "/v0/latest/{current_account_id}/{predecessor_id}/{key}": { "get": { "description": "Fetch the latest value for one exact key under one predecessor and contract.", "operationId": "get_latest_key", "parameters": [ { "description": "Contract account whose FastData keys were written.", "example": "social.near", "in": "path", "name": "current_account_id", "required": true, "schema": { "type": "string" } }, { "description": "Calling account that wrote the FastData keys.", "example": "james.near", "in": "path", "name": "predecessor_id", "required": true, "schema": { "type": "string" } }, { "description": "Exact FastData key to return.", "example": "graph/follow/sleet.near", "in": "path", "name": "key", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" } ], "page_token": "opaque-next-page-token" }, "schema": { "$ref": "#/components/schemas/ListResponse" } } }, "description": "Latest rows for the selected predecessor, account, and key" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch the latest row for one exact key under one predecessor and contract", "tags": [ "latest" ], "x-fastnear-slug": "get_latest_key", "x-fastnear-title": "KV FastData API - Latest by Exact Key" } }, "/v0/multi": { "post": { "description": "Fetch the latest FastData row for up to 100 keys in a single request.", "operationId": "multi", "requestBody": { "content": { "application/json": { "example": { "include_metadata": true, "keys": [ "social.near/james.near/graph/follow/sleet.near", "social.near/james.near/graph/follow/missing" ] }, "schema": { "$ref": "#/components/schemas/MultiRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "entries": [ { "action_index": 0, "block_height": 183302718, "block_timestamp": 1769731630602682600, "current_account_id": "social.near", "key": "graph/follow/sleet.near", "predecessor_id": "james.near", "receipt_id": "gaiLdGpaRwaunXUFnnz9VNj8V7cY18ZPAt2QfZazBkk", "signer_id": "james.near", "tx_hash": "FK7qDhHv4otg2wPGrE3DKFjvmmjHhUKBxQDkcAsdH5k3", "value": "" }, null ] }, "schema": { "$ref": "#/components/schemas/MultiResponse" } } }, "description": "Latest rows for the requested keys" }, "400": { "content": { "application/json": { "example": { "error": "invalid page token" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Invalid key filter or page token" }, "500": { "content": { "application/json": { "example": { "error": "internal server error" }, "schema": { "$ref": "#/components/schemas/ApiError" } } }, "description": "Scylla query failure" } }, "summary": "Fetch the latest rows for multiple fully qualified keys", "tags": [ "latest" ], "x-fastnear-slug": "multi", "x-fastnear-title": "KV FastData API - Multi-Key Lookup" } } }, "servers": [ { "description": "Mainnet", "url": "https://kv.main.fastnear.com" }, { "description": "Testnet", "url": "https://kv.test.fastnear.com" } ] }