{ "openapi": "3.1.1", "info": { "title": "AR.IO Gateway", "version": "0.0.1", "x-logo": { "url": "https://ar.io/wp-content/uploads/2022/02/ar-io-FINAL-LOGO-SHADOW.png" }, "description": "AR.IO Gateways are the interface between users and the Permaweb. Each Gateway acts like a “Permaweb Service\nProvider” and supports multiple, value-added, low-trust services for users and applications.\n\nThe AR.IO HTTP API is served by all AR.IO Gateways, and is used by all Arweave clients looking to read, write and query data. It supports the following capabilities\n- seeding layer one transactions to the greater Arweave network\n- caching and serving chain and transaction data\n- resolving friendly names to transaction data with the Arweave Name System\n- indexing and querying layer one and two transactions\n- proxy for Arweave nodes serving the Arweave HTTP API\n\n## Errors\n\nThe API uses standard HTTP status codes to indicate the success or failure of the API call.\n\n## Authentication\n\nAll inbound transactions to the Arweave network must contain a valid signature from an Arweave wallet with appropriate amount of AR tokens. At this time, clients are not required to sign their requests for outbound data from the Arweave network.\n", "license": { "name": "GNU Affero General Public License v3.0", "identifier": "AGPL-3.0-only" } }, "tags": [ { "name": "Gateway", "description": "Operations related to the AR.IO Gateway server itself, including health checks, metrics, and gateway-specific information\n" }, { "name": "Data", "description": "Core data retrieval operations for accessing transaction and data item content. Supports manifest resolution,\nrange requests, caching, and verification status. These endpoints serve as the primary interface for retrieving\ndata from the Permaweb.\n" }, { "name": "Network", "description": "Get Arweave node info, peers and nework status\n" }, { "name": "Pricing", "description": "Get the price (in winston) for an amount of bytes\n" }, { "name": "Wallets", "description": "Get Arweave wallet balance and last transaction information\n" }, { "name": "Blocks", "description": "Get current or historical Arweave block information\n" }, { "name": "Transactions", "description": "Submit a new Arweave transaction or get existing transaction information\n" }, { "name": "Chunks", "description": "Upload Arweave data chunks or get existing chunk offset information\n" }, { "name": "ArNS", "description": "Get data from the AR.IO Gateway Arweave Name System\n" }, { "name": "Index Querying", "description": "Get data from the AR.IO Gateway index using GQL\n" }, { "name": "Farcaster Frames", "description": "Retrieve and interact with Farcaster Frames using Arweave transactions.\n" }, { "name": "Admin", "description": "Access several password protected features and functions specific to your AR.IO Gateway.\n" }, { "name": "Rate Limiting", "description": "Query and manage rate limit bucket balances. Supports both public balance queries and top-ups via x402 payments or admin authentication.\n\n**⚠️ EXPERIMENTAL FEATURES**: The rate limiter and x402 payment protocol are experimental features subject to change. API endpoints, parameters, behavior, and configuration options (environment variables) may evolve in future releases as these systems continue to be developed. See [docs/x402-and-rate-limiting.md](https://github.com/ar-io/ar-io-node/blob/develop/docs/x402-and-rate-limiting.md) for comprehensive documentation.\n" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "apiToken", "description": "ADMIN_API_KEY set in your .env file." } }, "schemas": { "Base64Url": { "type": "string", "pattern": "^[A-Za-z0-9_-]+$" }, "Base64Url43": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{43}$" }, "Base64Url64": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{64}$" }, "Base64Url4364": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{43}$|^[0-9a-zA-Z_-]{64}$" }, "WinstonAmount": { "type": "string", "pattern": "^[0-9]{1,21}$" }, "NumericString": { "type": "string", "pattern": "^[0-9]+$" }, "IntegerOrNumericString": { "description": "A value that can be either an integer or a string representation of an integer", "anyOf": [ { "type": "integer" }, { "type": "string", "pattern": "^[0-9]+$" } ] }, "TagList": { "type": "array", "maxItems": 2048, "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{1,2731}$" }, "value": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{1,2731}$" } } } }, "Owner": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{1,683}$" }, "Signature": { "type": "string", "pattern": "^[0-9a-zA-Z_-]{1,683}$" }, "ByteRange": { "type": "string", "pattern": "^bytes=\\d*-\\d*(?:,\\d*-\\d*)*$", "description": "HTTP byte range specifying which parts of the data to retrieve.\nSupports single ranges (e.g. \"bytes=0-1023\") and multiple ranges (e.g. \"bytes=0-50,100-150\").\n", "example": "bytes=0-1023" }, "CacheStatus": { "type": "string", "enum": [ "HIT", "MISS" ], "description": "Indicates whether the data was served from cache" }, "VerificationStatus": { "type": "string", "enum": [ true, false ], "description": "Indicates whether the data has been verified" }, "Block": { "type": "object", "properties": { "usd_to_ar_rate": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/Base64Url" } }, "scheduled_usd_to_ar_rate": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/components/schemas/Base64Url" } }, "packing_2_5_threshold": { "$ref": "#/components/schemas/Base64Url" }, "strict_data_split_threshold": { "$ref": "#/components/schemas/NumericString" }, "nonce": { "$ref": "#/components/schemas/Base64Url" }, "previous_block": { "$ref": "#/components/schemas/Base64Url64" }, "timestamp": { "type": "integer" }, "last_retarget": { "type": "integer" }, "diff": { "$ref": "#/components/schemas/IntegerOrNumericString" }, "height": { "type": "integer" }, "hash": { "$ref": "#/components/schemas/Base64Url4364" }, "txs": { "type": "array", "minItems": 0, "maxItems": 1000, "items": { "$ref": "#/components/schemas/Base64Url43" } }, "tx_root": { "$ref": "#/components/schemas/Base64Url43" }, "tx_tree": { "type": "array", "maxItems": 0, "items": { "type": "string" } }, "wallet_list": { "$ref": "#/components/schemas/Base64Url4364" }, "reward_addr": { "$ref": "#/components/schemas/Base64Url43" }, "tags": { "$ref": "#/components/schemas/TagList" }, "reward_pool": { "$ref": "#/components/schemas/IntegerOrNumericString" }, "weave_size": { "$ref": "#/components/schemas/IntegerOrNumericString" }, "block_size": { "$ref": "#/components/schemas/IntegerOrNumericString" }, "cumulative_diff": { "$ref": "#/components/schemas/NumericString" }, "hash_list_merkle": { "$ref": "#/components/schemas/Base64Url64" }, "poa": { "type": "object", "properties": { "option": { "$ref": "#/components/schemas/NumericString" }, "tx_path": { "$ref": "#/components/schemas/Base64Url" }, "data_path": { "$ref": "#/components/schemas/Base64Url" }, "chunk": { "$ref": "#/components/schemas/Base64Url" } } } }, "required": [ "nonce", "previous_block", "timestamp", "last_retarget", "diff", "height", "hash", "indep_hash", "txs", "tx_root", "wallet_list", "reward_addr", "tags", "reward_pool", "weave_size", "block_size", "poa" ] }, "Chunk": { "type": "object", "properties": { "tx_path": { "$ref": "#/components/schemas/Base64Url" }, "packing": { "type": "string", "pattern": "^unpacked$" }, "data_path": { "$ref": "#/components/schemas/Base64Url" }, "chunk": { "$ref": "#/components/schemas/Base64Url" } }, "required": [ "tx_path", "packing", "data_path", "chunk" ] }, "Transaction": { "type": "object", "properties": { "format": { "type": "integer" }, "id": { "$ref": "#/components/schemas/Base64Url43" }, "last_tx": { "$ref": "#/components/schemas/Base64Url4364" }, "owner": { "$ref": "#/components/schemas/Owner" }, "tags": { "$ref": "#/components/schemas/TagList" }, "target": { "$ref": "#/components/schemas/Base64Url43" }, "quantity": { "$ref": "#/components/schemas/WinstonAmount" }, "data": { "$ref": "#/components/schemas/Base64Url" }, "data_tree": { "type": "array", "items": { "type": "string" } }, "data_root": { "$ref": "#/components/schemas/Base64Url" }, "reward": { "$ref": "#/components/schemas/WinstonAmount" }, "signature": { "$ref": "#/components/schemas/Signature" } }, "required": [ "format", "id", "last_tx", "owner", "tags", "target", "quantity", "data", "data_tree", "data_root", "reward", "signature" ] }, "TransactionOffset": { "type": "object", "properties": { "size": { "$ref": "#/components/schemas/NumericString" }, "offset": { "$ref": "#/components/schemas/NumericString" } }, "required": [ "size", "offset" ] }, "TransactionStatus": { "type": "object", "properties": { "block_height": { "type": "integer" }, "block_indep_hash": { "$ref": "#/components/schemas/Base64Url64" }, "number_of_confirmations": { "type": "integer" } }, "required": [ "block_height", "block_indep_hash", "number_of_confirmations" ] }, "Mempool": { "type": "array", "items": { "$ref": "#/components/schemas/Base64Url43" } }, "NetworkInfo": { "type": "object", "properties": { "network": { "type": "string" }, "version": { "type": "integer" }, "release": { "type": "integer" }, "current": { "$ref": "#/components/schemas/Base64Url64" }, "blocks": { "type": "integer" }, "peers": { "type": "integer" }, "queue_length": { "type": "integer" }, "node_state_latency": { "type": "integer" } }, "required": [ "network", "version", "release", "current", "blocks", "peers", "queue_length", "node_state_latency" ] }, "PeerList": { "type": "array", "items": { "type": "string", "pattern": "^[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}:\\d+$" } }, "Height": { "type": "string", "pattern": "^[0-9]{16}$" }, "ArNSResolution": { "type": "object", "description": "Response containing ArNS name resolution details", "properties": { "txId": { "$ref": "#/components/schemas/Base64Url43", "description": "The resolved transaction ID" }, "ttlSeconds": { "type": "integer", "description": "Time-to-live in seconds for this resolution" }, "processId": { "type": "string", "description": "AO process ID" }, "resolvedAt": { "type": "integer", "description": "Unix timestamp when the name was resolved" }, "index": { "type": "integer", "description": "Index of the name in the sorted list of names" }, "limit": { "type": "integer", "description": "The undername limit for the base ArNS name" } }, "required": [ "txId", "ttlSeconds", "processId", "resolvedAt", "index", "limit" ] } }, "requestBodies": { "QueueTxRequest": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Base64Url43", "description": "TX ID of the transaction you would like to prioritize." } } }, "examples": { "example1": { "value": { "id": "3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ" } } } } } } }, "responses": { "MissingId": { "description": "Bad Request. Id is required.", "content": { "text/plain": { "schema": { "type": "string", "example": "Must provide 'id'" } } } }, "MissingIdOrBypassFilter": { "description": "Bad Request. The request is missing required parameters.", "content": { "text/plain": { "schema": { "type": "string" }, "examples": { "missingId": { "summary": "ID is required", "value": "Must provide 'id'" }, "missingFilter": { "summary": "bypassFilter must be a boolean", "value": "'bypassFilter' must be a boolean" } } } } }, "QueueTxSuccess": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "TX queued" } }, "required": [ "message" ] } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "text/plain": { "schema": { "type": "string", "example": "Unauthorized" } } } }, "ServerError": { "description": "Internal Server Error", "content": { "text/plain": { "schema": { "type": "string", "example": "Internal Server Error" } } } } } }, "paths": { "/": { "get": { "tags": [ "Gateway" ], "summary": "Gateway Info or Apex Content", "description": "Returns either gateway information or serves content based on configuration:\n\n- If neither APEX_TX_ID nor APEX_ARNS_NAME is set, returns gateway information\n- If APEX_TX_ID is set, serves that transaction's content\n- If APEX_ARNS_NAME is set, resolves and serves that ArNS name's content\n\nThe Content-Type of the response will match the content type of the transaction or ArNS-resolved data (e.g., text/html for HTML documents, application/json for JSON documents, application/octet-stream for binary data, etc.).\n", "responses": { "200": { "description": "Either gateway information or transaction/ArNS content", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "description": "Gateway information", "properties": { "wallet": { "$ref": "#/components/schemas/Base64Url43", "description": "Gateway wallet address" }, "processId": { "$ref": "#/components/schemas/Base64Url43", "description": "Gateway process ID" }, "ans104UnbundleFilter": { "type": "object", "description": "Configuration for ANS-104 unbundling filter" }, "ans104IndexFilter": { "type": "object", "description": "Configuration for ANS-104 indexing filter" }, "supportedManifestVersions": { "type": "array", "description": "List of supported manifest versions", "items": { "type": "string", "enum": [ "0.1.0", "0.2.0" ] } }, "release": { "type": "string", "description": "Gateway software release version" } }, "required": [ "processId", "supportedManifestVersions", "release" ] } ] } }, "application/octet-stream": { "schema": { "type": "string", "format": "binary", "description": "Transaction or ArNS content when APEX_TX_ID or APEX_ARNS_NAME is set" } } } } } } }, "/ar-io/healthcheck": { "get": { "tags": [ "Gateway" ], "summary": "Health check endpoint", "description": "Get the current health status of the AR.IO Gateway.", "responses": { "200": { "description": "Health check response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "unhealthy" ], "description": "Current health status of the gateway" }, "uptime": { "type": "number", "description": "Process uptime in seconds" }, "date": { "type": "string", "format": "date-time", "description": "Current server timestamp" }, "reasons": { "type": "array", "items": { "type": "string" }, "description": "Array of reasons if status is unhealthy" } }, "required": [ "status", "uptime", "date" ] } } } } } } }, "/ar-io/info": { "get": { "tags": [ "Gateway" ], "summary": "Get AR.IO Gateway information", "description": "Returns information about the AR.IO Gateway, including:\n- Gateway wallet address\n- Process ID\n- ANS-104 filter configurations\n- Supported manifest versions\n- Gateway software release version\n- Bundler service URLs for data upload service discovery\n- Rate limiter configuration (if enabled)\n- x402 payment protocol configuration (if enabled)\n", "responses": { "200": { "description": "Gateway information response", "content": { "application/json": { "schema": { "type": "object", "properties": { "wallet": { "$ref": "#/components/schemas/Base64Url43", "description": "Gateway wallet address" }, "processId": { "$ref": "#/components/schemas/Base64Url43" }, "ans104UnbundleFilter": { "type": "object", "description": "Configuration for ANS-104 unbundling filter" }, "ans104IndexFilter": { "type": "object", "description": "Configuration for ANS-104 indexing filter" }, "supportedManifestVersions": { "type": "array", "description": "List of supported manifest versions", "items": { "type": "string", "enum": [ "0.1.0", "0.2.0" ] } }, "release": { "type": "string", "description": "Gateway software release version" }, "services": { "type": "object", "description": "Service discovery information", "properties": { "bundlers": { "type": "array", "description": "List of bundler service URLs for data upload service discovery", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Bundler service URL", "example": "https://turbo.ardrive.io/" } }, "required": [ "url" ] } } }, "required": [ "bundlers" ] }, "rateLimiter": { "type": "object", "description": "Rate limiter configuration (only present when rate limiting is enabled)", "properties": { "enabled": { "type": "boolean", "description": "Whether rate limiting is enabled", "example": true }, "dataEgress": { "type": "object", "description": "Data egress rate limiting configuration", "properties": { "buckets": { "type": "object", "description": "Token bucket configurations for rate limiting", "properties": { "resource": { "type": "object", "description": "Per-resource (transaction ID) rate limits", "properties": { "capacity": { "type": "number", "description": "Maximum tokens in bucket (1 token = 1 KiB)", "example": 1000000 }, "refillRate": { "type": "number", "description": "Tokens added per second", "example": 100 }, "capacityBytes": { "type": "number", "description": "Maximum bytes in bucket (capacity * 1024)", "example": 1024000000 }, "refillRateBytesPerSec": { "type": "number", "description": "Bytes added per second (refillRate * 1024)", "example": 102400 } }, "required": [ "capacity", "refillRate", "capacityBytes", "refillRateBytesPerSec" ] }, "ip": { "type": "object", "description": "Per-IP address rate limits", "properties": { "capacity": { "type": "number", "description": "Maximum tokens in bucket (1 token = 1 KiB)", "example": 100000 }, "refillRate": { "type": "number", "description": "Tokens added per second", "example": 20 }, "capacityBytes": { "type": "number", "description": "Maximum bytes in bucket (capacity * 1024)", "example": 102400000 }, "refillRateBytesPerSec": { "type": "number", "description": "Bytes added per second (refillRate * 1024)", "example": 20480 } }, "required": [ "capacity", "refillRate", "capacityBytes", "refillRateBytesPerSec" ] } }, "required": [ "resource", "ip" ] } }, "required": [ "buckets" ] } }, "required": [ "enabled", "dataEgress" ] }, "x402": { "type": "object", "description": "x402 payment protocol configuration (only present when x402 is enabled)", "properties": { "enabled": { "type": "boolean", "description": "Whether x402 payment protocol is enabled", "example": true }, "network": { "type": "string", "description": "Blockchain network for payments", "enum": [ "base", "base-sepolia" ], "example": "base-sepolia" }, "walletAddress": { "type": "string", "description": "Gateway wallet address for receiving payments", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }, "facilitatorUrl": { "type": "string", "format": "uri", "description": "x402 facilitator service URL", "example": "https://x402.org/facilitator" }, "dataEgress": { "type": "object", "description": "Data egress payment configuration", "properties": { "pricing": { "type": "object", "description": "Pricing information for data egress", "properties": { "perBytePrice": { "type": "number", "description": "Price in USDC per byte", "example": 1e-10 }, "minPrice": { "type": "number", "description": "Minimum price in USDC per request", "example": 0.001 }, "maxPrice": { "type": "number", "description": "Maximum price in USDC per request", "example": 1 }, "currency": { "type": "string", "description": "Payment currency", "enum": [ "USDC" ], "example": "USDC" }, "exampleCosts": { "type": "object", "description": "Example costs for common data sizes", "properties": { "1KB": { "type": "number", "description": "Cost for 1 kilobyte in USDC", "example": 0.001 }, "1MB": { "type": "number", "description": "Cost for 1 megabyte in USDC", "example": 0.0001024 }, "1GB": { "type": "number", "description": "Cost for 1 gigabyte in USDC", "example": 0.1048576 } }, "required": [ "1KB", "1MB", "1GB" ] } }, "required": [ "perBytePrice", "minPrice", "maxPrice", "currency", "exampleCosts" ] }, "rateLimiterCapacityMultiplier": { "type": "number", "description": "Capacity multiplier for paid tier (applied to rate limiter buckets)", "example": 10 } }, "required": [ "pricing", "rateLimiterCapacityMultiplier" ] } }, "required": [ "enabled", "network", "walletAddress", "facilitatorUrl", "dataEgress" ] } }, "required": [ "processId", "supportedManifestVersions", "release", "bundlers" ] } } } } } } }, "/ar-io/peers": { "get": { "tags": [ "Gateway" ], "summary": "Get AR.IO Gateway peer information", "description": "Returns information about AR.IO Gateway peers and Arweave node peers.\nFor gateways, includes both data and chunk weights used for peer selection.\nPeer keys are formatted as host:port.\n", "responses": { "200": { "description": "Peer information response", "content": { "application/json": { "schema": { "type": "object", "properties": { "gateways": { "type": "object", "description": "AR.IO Gateway peers with their weights", "additionalProperties": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Full URL of the gateway peer", "example": "https://gateway.example.com" }, "dataWeight": { "type": "number", "minimum": 1, "maximum": 100, "description": "Weight for data retrieval operations", "example": 50 }, "chunkWeight": { "type": "number", "minimum": 1, "maximum": 100, "description": "Weight for chunk retrieval operations", "example": 50 } }, "required": [ "url", "dataWeight", "chunkWeight" ] } }, "arweaveNodes": { "type": "object", "description": "Arweave node peers with their metadata", "additionalProperties": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL of the Arweave node peer", "example": "http://arweave.example.com:1984" }, "blocks": { "type": "number", "description": "Number of blocks stored by this peer", "example": 165967 }, "height": { "type": "number", "description": "Current block height of this peer", "example": 1732652 }, "lastSeen": { "type": "number", "description": "Unix timestamp when peer was last seen", "example": 1755190447700 } } } } }, "required": [ "gateways", "arweaveNodes" ], "example": { "gateways": { "gateway.example.com:443": { "url": "https://gateway.example.com", "dataWeight": 50, "chunkWeight": 50 } }, "arweaveNodes": { "arweave.example.com:1984": { "url": "http://arweave.example.com:1984", "blocks": 165967, "height": 1732652, "lastSeen": 1755190447700 } } } } } } } } } }, "/ar-io/__gateway_metrics": { "get": { "tags": [ "Gateway" ], "summary": "Get Prometheus metrics", "description": "Returns metrics in Prometheus format for monitoring the Gateway's performance and status.\nThese metrics include various counters, gauges, and histograms tracking:\n- HTTP request statistics\n- Transaction processing metrics\n- System resource usage\n- Cache performance\n- Bundle processing statistics\n", "responses": { "200": { "description": "Prometheus metrics response", "content": { "text/plain": { "schema": { "type": "string", "description": "Metrics in Prometheus format", "example": "# HELP errors_total Total error count\n# TYPE errors_total counter\nerrors_total 0\n\n# HELP uncaught_exceptions_total Count of uncaught exceptions\n# TYPE uncaught_exceptions_total counter\nuncaught_exceptions_total 0\n" } } } } } } }, "/{txId}": { "get": { "tags": [ "Data" ], "summary": "Get transaction or data item content", "description": "Get the content of a specified transaction or data item. Supports manifest path resolution,\nrange requests, and returns various informational headers about data verification and caching status.\n\nFor ANS-104 data items, offset headers are returned to help navigate bundle hierarchies:\n- Root offset headers (X-AR-IO-Root-Data-Item-Offset, X-AR-IO-Root-Data-Offset) provide byte offsets from the start of the root L1 transaction\n- Parent offset headers provide byte offsets from the start of the immediate parent bundle's payload\n- Offset relationships: rootDataItemOffset = rootParentOffset + offset, rootDataOffset = rootParentOffset + dataOffset\n", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } }, { "name": "Range", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ByteRange" }, "description": "Byte range(s) to retrieve" } ], "responses": { "200": { "description": "Successful response", "headers": { "Accept-Ranges": { "schema": { "type": "string", "example": "bytes" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=2592000, immutable" } }, "Content-Length": { "schema": { "type": "string", "example": 1024 } }, "Content-Type": { "schema": { "type": "string", "example": "application/octet-stream" } }, "X-Cache": { "schema": { "$ref": "#/components/schemas/CacheStatus", "example": "HIT" } }, "X-AR-IO-Verified": { "schema": { "$ref": "#/components/schemas/VerificationStatus", "example": true } }, "X-AR-IO-Digest": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "Content-Digest": { "schema": { "type": "string", "description": "RFC 9530 compliant digest header with SHA-256", "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "ETag": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "X-AR-IO-Root-Transaction-Id": { "schema": { "$ref": "#/components/schemas/Base64Url43", "description": "For data items, the root transaction ID", "example": "283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc" } }, "X-AR-IO-Hops": { "schema": { "type": "integer", "example": 1 } }, "X-AR-IO-Stable": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data is before max fork depth (stable on chain)", "example": "true" }, "X-AR-IO-Trusted": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data source is trusted", "example": "true" }, "X-AR-IO-Data-Id": { "schema": { "type": "string" }, "description": "The data ID being served (may differ from txId for manifests)", "example": "YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE" }, "Content-Encoding": { "schema": { "type": "string" }, "description": "Content encoding when present (e.g., gzip, br)", "example": "gzip" }, "X-AR-IO-Root-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2048 }, "X-AR-IO-Root-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2176 }, "X-AR-IO-Data-Item-Root-Parent-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)", "example": 1536 }, "X-AR-IO-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 512 }, "X-AR-IO-Data-Item-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 640 }, "X-AR-IO-Data-Item-Size": { "schema": { "type": "integer" }, "description": "Total size of data item including headers and payload in bytes (ANS-104 bundles only)", "example": 2092 } } }, "206": { "description": "Partial content for range requests", "headers": { "Accept-Ranges": { "schema": { "type": "string", "example": "bytes" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=2592000, immutable" } }, "Content-Range": { "schema": { "type": "string", "example": "bytes 0-1023/146515" } }, "Content-Type": { "schema": { "type": "string", "example": "application/octet-stream" } }, "X-Cache": { "schema": { "$ref": "#/components/schemas/CacheStatus", "example": "HIT" } }, "X-AR-IO-Verified": { "schema": { "$ref": "#/components/schemas/VerificationStatus", "example": true } }, "X-AR-IO-Digest": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "Content-Digest": { "schema": { "type": "string", "description": "RFC 9530 compliant digest header with SHA-256", "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "ETag": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "X-AR-IO-Root-Transaction-Id": { "schema": { "$ref": "#/components/schemas/Base64Url43", "description": "For data items, the root transaction ID", "example": "283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc" } }, "X-AR-IO-Hops": { "schema": { "type": "integer", "example": 1 } }, "X-AR-IO-Stable": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data is before max fork depth (stable on chain)", "example": "true" }, "X-AR-IO-Trusted": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data source is trusted", "example": "true" }, "X-AR-IO-Data-Id": { "schema": { "type": "string" }, "description": "The data ID being served (may differ from txId for manifests)", "example": "YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE" }, "Content-Encoding": { "schema": { "type": "string" }, "description": "Content encoding when present (e.g., gzip, br)", "example": "gzip" }, "X-AR-IO-Root-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2048 }, "X-AR-IO-Root-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2176 }, "X-AR-IO-Data-Item-Root-Parent-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)", "example": 1536 }, "X-AR-IO-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 512 }, "X-AR-IO-Data-Item-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 640 }, "X-AR-IO-Data-Item-Size": { "schema": { "type": "integer" }, "description": "Total size of data item including headers and payload in bytes (ANS-104 bundles only)", "example": 2092 } } }, "301": { "description": "Redirect for manifest paths without trailing slash" }, "404": { "description": "Data not found or blocked" }, "416": { "description": "Range not satisfiable" } } }, "head": { "tags": [ "Data" ], "summary": "Get transaction or data item headers", "description": "Get the headers for a specified transaction or data item without the content.\nReturns the same headers as the GET request.\n", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } }, { "name": "Range", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ByteRange" }, "description": "Byte range(s) to check" } ], "responses": { "200": { "description": "Successful response", "headers": { "Accept-Ranges": { "schema": { "type": "string", "example": "bytes" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=2592000, immutable" } }, "Content-Length": { "schema": { "type": "string", "example": 1024 } }, "Content-Type": { "schema": { "type": "string", "example": "application/octet-stream" } }, "X-Cache": { "schema": { "$ref": "#/components/schemas/CacheStatus", "example": "HIT" } }, "X-AR-IO-Verified": { "schema": { "$ref": "#/components/schemas/VerificationStatus", "example": true } }, "X-AR-IO-Digest": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "Content-Digest": { "schema": { "type": "string", "description": "RFC 9530 compliant digest header with SHA-256", "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "ETag": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "X-AR-IO-Root-Transaction-Id": { "schema": { "$ref": "#/components/schemas/Base64Url43", "description": "For data items, the root transaction ID", "example": "283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc" } }, "X-AR-IO-Hops": { "schema": { "type": "integer", "example": 1 } } } } } } }, "/raw/{txId}": { "get": { "tags": [ "Data" ], "summary": "Get raw transaction data", "description": "Get the raw content of a specified transaction without manifest resolution.\n\nFor ANS-104 data items, offset headers are returned to help navigate bundle hierarchies:\n- Root offset headers (X-AR-IO-Root-Data-Item-Offset, X-AR-IO-Root-Data-Offset) provide byte offsets from the start of the root L1 transaction\n- Parent offset headers provide byte offsets from the start of the immediate parent bundle's payload\n- Offset relationships: rootDataItemOffset = rootParentOffset + offset, rootDataOffset = rootParentOffset + dataOffset\n", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } }, { "name": "Range", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ByteRange" }, "description": "Byte range(s) to retrieve" } ], "responses": { "200": { "description": "Successful response", "headers": { "Accept-Ranges": { "schema": { "type": "string", "example": "bytes" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=2592000, immutable" } }, "Content-Length": { "schema": { "type": "string", "example": 1024 } }, "Content-Type": { "schema": { "type": "string", "example": "application/octet-stream" } }, "X-Cache": { "schema": { "$ref": "#/components/schemas/CacheStatus", "example": "HIT" } }, "X-AR-IO-Verified": { "schema": { "$ref": "#/components/schemas/VerificationStatus", "example": true } }, "X-AR-IO-Digest": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "Content-Digest": { "schema": { "type": "string", "description": "RFC 9530 compliant digest header with SHA-256", "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "ETag": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "X-AR-IO-Root-Transaction-Id": { "schema": { "$ref": "#/components/schemas/Base64Url43", "description": "For data items, the root transaction ID", "example": "283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc" } }, "X-AR-IO-Hops": { "schema": { "type": "integer", "example": 1 } }, "X-AR-IO-Stable": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data is before max fork depth (stable on chain)", "example": "true" }, "X-AR-IO-Trusted": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data source is trusted", "example": "true" }, "X-AR-IO-Data-Id": { "schema": { "type": "string" }, "description": "The data ID being served (may differ from txId for manifests)", "example": "YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE" }, "Content-Encoding": { "schema": { "type": "string" }, "description": "Content encoding when present (e.g., gzip, br)", "example": "gzip" }, "X-AR-IO-Root-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2048 }, "X-AR-IO-Root-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2176 }, "X-AR-IO-Data-Item-Root-Parent-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)", "example": 1536 }, "X-AR-IO-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 512 }, "X-AR-IO-Data-Item-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 640 }, "X-AR-IO-Data-Item-Size": { "schema": { "type": "integer" }, "description": "Total size of data item including headers and payload in bytes (ANS-104 bundles only)", "example": 2092 } } }, "206": { "description": "Partial content for range requests", "headers": { "Accept-Ranges": { "schema": { "type": "string", "example": "bytes" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=2592000, immutable" } }, "Content-Range": { "schema": { "type": "string", "example": "bytes 0-1023/146515" } }, "Content-Type": { "schema": { "type": "string", "example": "application/octet-stream" } }, "X-Cache": { "schema": { "$ref": "#/components/schemas/CacheStatus", "example": "HIT" } }, "X-AR-IO-Verified": { "schema": { "$ref": "#/components/schemas/VerificationStatus", "example": true } }, "X-AR-IO-Digest": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "Content-Digest": { "schema": { "type": "string", "description": "RFC 9530 compliant digest header with SHA-256", "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "ETag": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "X-AR-IO-Root-Transaction-Id": { "schema": { "$ref": "#/components/schemas/Base64Url43", "description": "For data items, the root transaction ID", "example": "283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc" } }, "X-AR-IO-Hops": { "schema": { "type": "integer", "example": 1 } }, "X-AR-IO-Stable": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data is before max fork depth (stable on chain)", "example": "true" }, "X-AR-IO-Trusted": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data source is trusted", "example": "true" }, "X-AR-IO-Data-Id": { "schema": { "type": "string" }, "description": "The data ID being served (may differ from txId for manifests)", "example": "YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE" }, "Content-Encoding": { "schema": { "type": "string" }, "description": "Content encoding when present (e.g., gzip, br)", "example": "gzip" }, "X-AR-IO-Root-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2048 }, "X-AR-IO-Root-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2176 }, "X-AR-IO-Data-Item-Root-Parent-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)", "example": 1536 }, "X-AR-IO-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 512 }, "X-AR-IO-Data-Item-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 640 }, "X-AR-IO-Data-Item-Size": { "schema": { "type": "integer" }, "description": "Total size of data item including headers and payload in bytes (ANS-104 bundles only)", "example": 2092 } } }, "404": { "description": "Data not found or blocked" }, "416": { "description": "Range not satisfiable" } } }, "head": { "tags": [ "Data" ], "summary": "Get raw transaction data headers", "description": "Get the headers for raw transaction data without manifest resolution", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } }, { "name": "Range", "in": "header", "required": false, "schema": { "$ref": "#/components/schemas/ByteRange" }, "description": "Byte range(s) to check" } ], "responses": { "200": { "description": "Successful response", "headers": { "Accept-Ranges": { "schema": { "type": "string", "example": "bytes" } }, "Cache-Control": { "schema": { "type": "string", "example": "public, max-age=2592000, immutable" } }, "Content-Length": { "schema": { "type": "string", "example": 1024 } }, "Content-Type": { "schema": { "type": "string", "example": "application/octet-stream" } }, "X-Cache": { "schema": { "$ref": "#/components/schemas/CacheStatus", "example": "HIT" } }, "X-AR-IO-Verified": { "schema": { "$ref": "#/components/schemas/VerificationStatus", "example": true } }, "X-AR-IO-Digest": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "Content-Digest": { "schema": { "type": "string", "description": "RFC 9530 compliant digest header with SHA-256", "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "ETag": { "schema": { "type": "string", "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" } }, "X-AR-IO-Root-Transaction-Id": { "schema": { "$ref": "#/components/schemas/Base64Url43", "description": "For data items, the root transaction ID", "example": "283VjqeZG65tPI6V0e-gucoHCaEBPL41_cI8rXVRbMc" } }, "X-AR-IO-Hops": { "schema": { "type": "integer", "example": 1 } }, "X-AR-IO-Stable": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data is before max fork depth (stable on chain)", "example": "true" }, "X-AR-IO-Trusted": { "schema": { "type": "string", "enum": [ "true", "false" ] }, "description": "Whether data source is trusted", "example": "true" }, "X-AR-IO-Data-Id": { "schema": { "type": "string" }, "description": "The data ID being served (may differ from txId for manifests)", "example": "YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE" }, "Content-Encoding": { "schema": { "type": "string" }, "description": "Content encoding when present (e.g., gzip, br)", "example": "gzip" }, "X-AR-IO-Root-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2048 }, "X-AR-IO-Root-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the root L1 transaction data (ANS-104 bundles only)", "example": 2176 }, "X-AR-IO-Data-Item-Root-Parent-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the immediate parent bundle's payload from the start of the root transaction (ANS-104 bundles only)", "example": 1536 }, "X-AR-IO-Data-Item-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data item header from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 512 }, "X-AR-IO-Data-Item-Data-Offset": { "schema": { "type": "integer" }, "description": "Byte offset of the data payload from the start of the immediate parent bundle's payload (ANS-104 bundles only)", "example": 640 }, "X-AR-IO-Data-Item-Size": { "schema": { "type": "integer" }, "description": "Total size of data item including headers and payload in bytes (ANS-104 bundles only)", "example": 2092 } } }, "404": { "description": "Data not found or blocked" }, "416": { "description": "Range not satisfiable for HEAD request" } } } }, "/info": { "get": { "tags": [ "Network" ], "summary": "Network and Gateway Status, alternate endpoint.", "description": "An alternative option for accessing network and Gateway status.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkInfo" } } } } } } }, "/peers": { "get": { "tags": [ "Network" ], "summary": "Get active peer list.", "description": "Gets a list of ip addresses for peers your Gateway is currently connected with.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeerList" } } } } } } }, "/height": { "get": { "tags": [ "Network" ], "summary": "Get current block height.", "description": "Gets the current block height of the Arweave network.", "responses": { "200": { "description": "200 response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Height" } } } } } } }, "/tx_anchor": { "get": { "tags": [ "Network" ], "summary": "Get the current transaction anchor.", "description": "Get the current transaction anchor of the Arweave network.", "responses": { "200": { "description": "200 response", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/Base64Url43" } } } } } } }, "/price/{size}": { "get": { "tags": [ "Pricing" ], "summary": "Get price to store an amount of data.", "description": "Get the price, in Winston, required to store a specified amount of data, in bytes, on the Arweave network.", "parameters": [ { "name": "size", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/NumericString" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "text/plain": { "schema": { "type": "integer" } } } } } } }, "/price/{size}/target": { "get": { "tags": [ "Pricing" ], "summary": "Get price to transfer AR into a wallet and store an amount of data", "description": "Get the price, in Winston, required to transfer AR into a wallet and store a specified amount of data, in bytes, on the Arweave network.\n", "parameters": [ { "name": "size", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/NumericString" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "text/html": { "schema": { "type": "integer" } } } } } } }, "/wallet/{address}/balance": { "get": { "tags": [ "Wallets" ], "summary": "Get the current balance of a wallet.", "description": "Get the current balance of AR, in Winston, of a specified wallet address.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "text/plain": { "schema": { "type": "integer" } } } } } } }, "/wallet/{address}/last_tx": { "get": { "tags": [ "Wallets" ], "summary": "Get the last transaction of a wallet.", "description": "Get the TX ID from the most recent transaction a specified wallet completed.", "parameters": [ { "name": "address", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/Base64Url43" } } } } } } }, "/current_block": { "get": { "tags": [ "Blocks" ], "summary": "Get information about the current block.", "description": "Get detailed information about the current block on the Arweave network.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Block" } } } } } } }, "/block/height/{height}": { "get": { "tags": [ "Blocks" ], "summary": "Get current block height.", "description": "Gets the current block height of the Arweave network.", "parameters": [ { "name": "height", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/NumericString" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Block" } } } } } } }, "/block/hash/{hash}": { "get": { "tags": [ "Blocks" ], "summary": "Get block by hash.", "description": "Get block information based on a block's hash.", "parameters": [ { "name": "hash", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url64" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Block" } } } } } } }, "/block/current": { "get": { "tags": [ "Blocks" ], "summary": "Alternative endpoint to get current block.", "description": "Alternative endpoint to `/current_block`, gets current block information.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Block" } } } } } } }, "/tx/pending": { "get": { "tags": [ "Transactions" ], "summary": "Get pending transactions.", "description": "Get list of transactions that are currently pending.", "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Mempool" } } } } } } }, "/tx/{txId}": { "get": { "tags": [ "Transactions" ], "summary": "Get information about a transaction.", "description": "Get detailed information about a specific transaction.", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } }, "/tx/{txId}/offset": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction offset information.", "description": "Get information about the size and offset of a specified transaction.", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionOffset" } } } } } } }, "/tx/{txId}/status": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction status.", "description": "Get the status of a specified transaction.", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatus" } } } } } } }, "/chunk/{offset}": { "get": { "tags": [ "Chunks" ], "summary": "Get chunk offset information.", "description": "Fetches information about the size and offset of a specified chunk.", "parameters": [ { "name": "offset", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag value for conditional request. Returns 304 if chunk hash matches.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response", "headers": { "ETag": { "description": "Entity tag based on chunk hash (when available)", "schema": { "type": "string" } }, "Content-Digest": { "description": "RFC 9530 compliant digest header with SHA-256 (when available)", "schema": { "type": "string", "example": "sha-256=:YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE=:" } }, "Content-Length": { "description": "Size of the response body in bytes", "schema": { "type": "integer" } }, "X-Cache": { "description": "Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).\nAlways present.", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] }, "example": "HIT" }, "X-AR-IO-Chunk-Source-Type": { "description": "Source type of the chunk data", "schema": { "type": "string" } }, "X-AR-IO-Chunk-Host": { "description": "Host that provided the chunk", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Chunk" } } } }, "304": { "description": "Not Modified - chunk hash matches If-None-Match header" }, "400": { "description": "Invalid offset parameter" }, "404": { "description": "Chunk not found" } } }, "head": { "tags": [ "Chunks" ], "summary": "Get chunk metadata without body.", "description": "Returns the same headers as GET but without the response body. Useful for checking chunk existence and metadata.", "parameters": [ { "name": "offset", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag value for conditional request. Returns 304 if chunk hash matches.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "200 response with headers only", "headers": { "Content-Type": { "description": "Media type of the response", "schema": { "type": "string" } }, "ETag": { "description": "Entity tag based on chunk hash (when available)", "schema": { "type": "string" } }, "Content-Digest": { "description": "RFC 9530 compliant digest header with SHA-256 (when available)", "schema": { "type": "string", "example": "sha-256=:YjNkZjM1YThhNjIxOGY2MTZlNTQ3YzFmZGE2YzE4ZjE=:" } }, "Content-Length": { "description": "Size of the response body in bytes", "schema": { "type": "integer" } }, "X-Cache": { "description": "Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).\nAlways present.", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] }, "example": "HIT" }, "X-AR-IO-Chunk-Source-Type": { "description": "Source type of the chunk data", "schema": { "type": "string" } }, "X-AR-IO-Chunk-Host": { "description": "Host that provided the chunk", "schema": { "type": "string" } } } }, "304": { "description": "Not Modified - chunk hash matches If-None-Match header" }, "400": { "description": "Invalid offset parameter" }, "404": { "description": "Chunk not found" } } } }, "/chunk/{offset}/data": { "get": { "tags": [ "Chunks" ], "summary": "Get chunk as raw binary data with metadata in headers.", "description": "Fetches chunk data as raw binary (application/octet-stream) with metadata in response headers.\nThis endpoint provides ~40% bandwidth savings compared to the base64url-encoded JSON endpoint.\n\nChunk boundaries and merkle tree structure:\n- Chunks are determined by Arweave's merkle tree structure (maximum 256 KiB per chunk)\n- When you request data at an arbitrary offset, the full chunk containing that offset is returned\n- Use X-Arweave-Chunk-Read-Offset to determine where to start reading within the returned chunk\n- Merkle proof headers (X-Arweave-Chunk-Data-Path, X-Arweave-Chunk-Data-Root) provide cryptographic verification\n\nOffset relationships:\n- X-Arweave-Chunk-Start-Offset: Weave position where this chunk begins\n- X-Arweave-Chunk-Tx-Start-Offset: Weave position where the containing transaction begins\n- X-Arweave-Chunk-Relative-Start-Offset: Chunk position within its transaction (Chunk-Start-Offset - Tx-Start-Offset)\n- X-Arweave-Chunk-Read-Offset: Byte offset within the returned chunk where your requested data starts\n\nExample: Requesting a specific byte\n- Request: GET /chunk/50100/data (you want byte 50100 of the weave)\n- Response might have:\n - X-Arweave-Chunk-Start-Offset: 50000 (chunk starts at weave byte 50000)\n - X-Arweave-Chunk-Tx-Start-Offset: 49500 (transaction starts at weave byte 49500)\n - X-Arweave-Chunk-Relative-Start-Offset: 500 (chunk is 500 bytes into the transaction)\n - X-Arweave-Chunk-Read-Offset: 100 (start reading at byte 100 of the chunk body)\n - Content-Length: 262144 (256 KiB chunk returned)\n- To get your data: read from byte 100 to end of the response body", "parameters": [ { "name": "offset", "in": "path", "required": true, "description": "Weave offset (0-based byte position in the weave)", "schema": { "type": "integer" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag value for conditional request. Returns 304 if chunk hash matches.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Raw binary chunk data with metadata in headers", "headers": { "Content-Type": { "description": "Media type of the response.\nAlways application/octet-stream for this endpoint.\nAlways present.", "schema": { "type": "string", "example": "application/octet-stream" } }, "Content-Length": { "description": "Size of the chunk data in bytes (maximum 256 KiB).\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Data-Path": { "description": "Base64url-encoded merkle proof path for this chunk.\nProvides cryptographic proof of the chunk's position in the merkle tree.\nUses base64url encoding (URL-safe), not standard base64.\nAlways present.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Data-Root": { "description": "Base64url-encoded merkle tree root hash.\nRoot of the merkle tree used to verify chunk integrity.\nUses base64url encoding (URL-safe), not standard base64.\nAlways present.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Start-Offset": { "description": "Start offset of this chunk in the weave (inclusive, 0-based byte position).\nThis is the weave-relative position where this chunk begins.\nTo calculate chunk end offset: startOffset + Content-Length.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Relative-Start-Offset": { "description": "Byte offset where this chunk starts within its containing transaction (inclusive, 0-based).\nCalculated as: X-Arweave-Chunk-Start-Offset - X-Arweave-Chunk-Tx-Start-Offset.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Read-Offset": { "description": "Byte offset within the returned chunk body where your requested data starts (0-based).\nSince full chunks are always returned (determined by merkle tree boundaries),\nthis tells you where to start reading within the response body to get the data at your requested offset.\nExample: if you request offset 50100 and the chunk starts at 50000, this will be 100.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Tx-Data-Size": { "description": "Total size of the containing transaction's data in bytes.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Tx-Path": { "description": "Base64url-encoded transaction-level merkle path.\nAlways present but may be empty string if transaction path is not available.\nUses base64url encoding (URL-safe), not standard base64.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Tx-Id": { "description": "The Arweave transaction ID (base64url) containing this chunk.\nAlways present.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Tx-Start-Offset": { "description": "Start offset of the containing transaction in the weave (inclusive, 0-based byte position).\nThis is the weave-relative position where the transaction begins.\nTo calculate transaction end offset: txStartOffset + X-Arweave-Chunk-Tx-Data-Size.\nAlways present.", "schema": { "type": "integer" } }, "X-Cache": { "description": "Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).\nAlways present.", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] }, "example": "HIT" }, "X-AR-IO-Chunk-Source-Type": { "description": "Source type of the chunk data (e.g., 'cache', 'origin', 'peer').\nPresent when source information is available.", "schema": { "type": "string" }, "example": "cache" }, "X-AR-IO-Chunk-Host": { "description": "Hostname or identifier of the source that provided this chunk.\nPresent when source host information is available.", "schema": { "type": "string" }, "example": "gateway.example.com" }, "ETag": { "description": "Strong ETag based on SHA-256 hash of chunk data (base64url-encoded).\nPresent only for cached chunks or HEAD requests to ensure hash accuracy.\nUse with If-None-Match header for conditional requests.", "schema": { "type": "string" }, "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" }, "Content-Digest": { "description": "RFC 9530 compliant digest header with SHA-256 hash of chunk data.\nPresent only for cached chunks or HEAD requests to ensure hash accuracy.\nFormat: sha-256=:: (uses standard base64, not base64url).", "schema": { "type": "string" }, "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "304": { "description": "Not Modified - chunk hash matches If-None-Match header" }, "400": { "description": "Invalid offset parameter" }, "404": { "description": "Chunk not found" }, "500": { "description": "Internal server error (e.g., merkle path parsing failed)" } } }, "head": { "tags": [ "Chunks" ], "summary": "Get chunk metadata without body.", "description": "Returns the same headers as GET but without the response body.\nUseful for checking chunk existence, getting metadata (boundaries, offsets, merkle proofs),\nand obtaining hashes (ETag, Content-Digest) without downloading the full chunk.", "parameters": [ { "name": "offset", "in": "path", "required": true, "description": "Weave offset (0-based byte position in the weave)", "schema": { "type": "integer" } }, { "name": "If-None-Match", "in": "header", "required": false, "description": "ETag value for conditional request. Returns 304 if chunk hash matches.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Chunk metadata in headers only", "headers": { "Content-Type": { "description": "Media type of the response (if body were returned)", "schema": { "type": "string", "example": "application/octet-stream" } }, "Content-Length": { "description": "Size of the raw chunk in bytes", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Data-Path": { "description": "Base64url-encoded merkle proof path for this chunk.\nProvides cryptographic proof of the chunk's position in the merkle tree.\nUses base64url encoding (URL-safe), not standard base64.\nAlways present.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Data-Root": { "description": "Base64url-encoded merkle tree root hash.\nRoot of the merkle tree used to verify chunk integrity.\nUses base64url encoding (URL-safe), not standard base64.\nAlways present.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Start-Offset": { "description": "Start offset of this chunk in the weave (inclusive, 0-based byte position).\nThis is the weave-relative position where this chunk begins.\nTo calculate chunk end offset: startOffset + Content-Length.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Relative-Start-Offset": { "description": "Byte offset where this chunk starts within its containing transaction (inclusive, 0-based).\nCalculated as: X-Arweave-Chunk-Start-Offset - X-Arweave-Chunk-Tx-Start-Offset.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Read-Offset": { "description": "Byte offset within the returned chunk body where your requested data starts (0-based).\nSince full chunks are always returned (determined by merkle tree boundaries),\nthis tells you where to start reading within the response body to get the data at your requested offset.\nExample: if you request offset 50100 and the chunk starts at 50000, this will be 100.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Tx-Data-Size": { "description": "Total size of the containing transaction's data in bytes.\nAlways present.", "schema": { "type": "integer" } }, "X-Arweave-Chunk-Tx-Path": { "description": "Base64url-encoded transaction-level merkle path.\nAlways present but may be empty string if transaction path is not available.\nUses base64url encoding (URL-safe), not standard base64.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Tx-Id": { "description": "The Arweave transaction ID (base64url) containing this chunk.\nAlways present.", "schema": { "type": "string" } }, "X-Arweave-Chunk-Tx-Start-Offset": { "description": "Start offset of the containing transaction in the weave (inclusive, 0-based byte position).\nThis is the weave-relative position where the transaction begins.\nTo calculate transaction end offset: txStartOffset + X-Arweave-Chunk-Tx-Data-Size.\nAlways present.", "schema": { "type": "integer" } }, "X-Cache": { "description": "Cache status indicating whether chunk was served from local cache (HIT) or retrieved from external source (MISS).\nAlways present.", "schema": { "type": "string", "enum": [ "HIT", "MISS" ] }, "example": "HIT" }, "X-AR-IO-Chunk-Source-Type": { "description": "Source type of the chunk data (e.g., 'cache', 'origin', 'peer').\nPresent when source information is available.", "schema": { "type": "string" }, "example": "cache" }, "X-AR-IO-Chunk-Host": { "description": "Hostname or identifier of the source that provided this chunk.\nPresent when source host information is available.", "schema": { "type": "string" }, "example": "gateway.example.com" }, "ETag": { "description": "Strong ETag based on SHA-256 hash of chunk data (base64url-encoded).\nPresent only for cached chunks or HEAD requests to ensure hash accuracy.\nUse with If-None-Match header for conditional requests.", "schema": { "type": "string" }, "example": "4ROTs2lTPAKbr8Y41WrjHu-2q-7S-m-yTuO7fAUzZI4" }, "Content-Digest": { "description": "RFC 9530 compliant digest header with SHA-256 hash of chunk data.\nPresent only for cached chunks or HEAD requests to ensure hash accuracy.\nFormat: sha-256=:: (uses standard base64, not base64url).", "schema": { "type": "string" }, "example": "sha-256=:4ROTs2lTPAKbr8Y41WrjHu+2q+7S+m+yTuO7fAUzZI4=:" } } }, "304": { "description": "Not Modified - chunk hash matches If-None-Match header" }, "400": { "description": "Invalid offset parameter" }, "404": { "description": "Chunk not found" }, "500": { "description": "Internal server error (e.g., merkle path parsing failed)" } } } }, "/graphql": { "post": { "tags": [ "Index Querying" ], "summary": "Query indexed data using GraphQL", "description": "GraphQL endpoint for querying indexed transaction and block data. Supports:\n- Transaction queries by ID, owner, recipient, tags, and bundle\n- Block queries by ID and height\n- Pagination and sorting\n- Rich metadata including sizes, content types, and signatures\n\nSee the GraphQL Playground at `/graphql` for full schema documentation and interactive querying.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "description": "GraphQL query string" }, "variables": { "type": "object", "description": "Query variables" } }, "example": { "query": "query {\n transaction(\n id: \"D6I-Ke9oLg7sU_PS4oADQmnyFRa1jj2Zs1DP9BltrFs\"\n ) {\n signature\n owner {\n address\n }\n bundledIn {\n id\n }\n block {\n height\n }\n }\n}\n" } } } } }, "responses": { "200": { "description": "Successful GraphQL response", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "description": "Query results", "example": "{\n \"transaction\": {\n \"signature\": \"4wh6PDJH6eyCKAWZoW26T0qt5NNjnVgyPjLs5HDR7fYgOyzEZF8FyIJiz01IRVvmXC9WZKvy2uLGiIdW4GtUNhs\",\n \"owner\": {\n \"address\": \"WbE3R_GcAalEP-VonRpL2P5TG30PJRA1-Tj20E_xIK0\"\n },\n \"bundledIn\": {\n \"id\": \"yU5ilscWlDecDhUmNcd24zqe9HmNZ31h31BxC_VcXIM\"\n },\n \"block\": null\n }\n}\n" }, "errors": { "type": "array", "description": "Query errors if any", "items": { "type": "object", "properties": { "message": { "type": "string" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "column": { "type": "integer" } } } }, "path": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "400": { "description": "Invalid GraphQL query" }, "500": { "description": "Server error" } } } }, "/ar-io/resolver/{name}": { "get": { "tags": [ "ArNS" ], "summary": "Get ArNS name resolution.", "description": "Get detailed information of a specified ArNS name.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful resolution of ArNS name", "headers": { "x-arns-resolved-id": { "schema": { "$ref": "#/components/schemas/Base64Url43" }, "description": "The resolved transaction ID" }, "x-arns-ttl-seconds": { "schema": { "type": "string" }, "description": "Time-to-live in seconds for this resolution" }, "x-arns-process-id": { "schema": { "type": "string" }, "description": "AO process ID" }, "x-arns-resolved-at": { "schema": { "type": "string" }, "description": "Unix timestamp when the name was resolved" }, "x-arns-record-index": { "schema": { "type": "number" }, "description": "Index of the name in the sorted list of names" }, "x-arns-undername-limit": { "schema": { "type": "number" }, "description": "The undername limit for the base ArNS name" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ArNSResolution" } } } }, "404": { "description": "ArNS name not found." } } } }, "/ar-io/admin/debug": { "get": { "tags": [ "Admin" ], "summary": "Admin debugging information.", "description": "Get detailed information about the current operational state of your AR.IO Gateway, including information about any current warnings or errors.", "operationId": "adminDebug", "responses": { "200": { "description": "Successful operation." }, "401": { "description": "Unauthorized, API key likely incorrect." } }, "security": [ { "bearerAuth": [] } ] } }, "/ar-io/admin/queue-tx": { "post": { "tags": [ "Admin" ], "summary": "Prioritize a transaction or bundle in the queue.", "description": "Stage a specific TX ID as priority for your Gateway to locate and index. This will trigger and queue bundle processing if the transaction is a bundle, and your Gateway is configured to unbundle and index.", "operationId": "adminQueueTx", "requestBody": { "$ref": "#/components/requestBodies/QueueTxRequest" }, "responses": { "200": { "$ref": "#/components/responses/QueueTxSuccess" }, "400": { "$ref": "#/components/responses/MissingId" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ] } }, "/ar-io/admin/queue-bundle": { "post": { "tags": [ "Admin" ], "summary": "Queue a bundle for indexing, bypassing any filter settings by default.", "description": "Queue a bundle for indexing, bypassing any filter settings by default.", "operationId": "adminQueueBundle", "requestBody": { "$ref": "#/components/requestBodies/QueueTxRequest" }, "responses": { "200": { "$ref": "#/components/responses/QueueTxSuccess" }, "400": { "$ref": "#/components/responses/MissingIdOrBypassFilter" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "bearerAuth": [] } ] } }, "/ar-io/admin/queue-data-item": { "post": { "tags": [ "Admin" ], "summary": "Queue data items for indexing", "description": "Queue one or more data items for indexing. This endpoint\naccepts an array of data item headers and prioritizes them for processing.\n", "operationId": "adminQueueDataItem", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "data_size": { "type": "integer", "description": "Size of the data item in bytes" }, "id": { "$ref": "#/components/schemas/Base64Url43", "description": "Data item ID" }, "owner": { "$ref": "#/components/schemas/Owner", "Description": "Data item signer's public key" }, "owner_address": { "$ref": "#/components/schemas/Base64Url43", "description": "Normalized address" }, "signature": { "$ref": "#/components/schemas/Signature", "description": "Data item signature" }, "tags": { "$ref": "#/components/schemas/TagList", "description": "Optional tags associated with the data item" }, "content_type": { "type": "string", "description": "Optional content type of the data item" }, "target": { "$ref": "#/components/schemas/Base64Url43", "description": "Optional target address" }, "anchor": { "$ref": "#/components/schemas/Base64Url43", "description": "Optional anchor" } }, "required": [ "data_size", "id", "owner", "owner_address", "signature" ] }, "minItems": 1 } } } }, "responses": { "200": { "description": "Data items successfully queued", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Data item(s) queued" } } } } } }, "400": { "description": "Invalid request body", "content": { "text/plain": { "schema": { "type": "string", "example": "Must provide array of data item headers" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ar-io/admin/bundle-status/{id}": { "get": { "tags": [ "Admin" ], "summary": "Get bundle processing status", "description": "Returns detailed status information about a bundle's processing state, including counts of data items,\nprocessing timestamps, and retry attempts. This endpoint helps monitor the progress and state of bundle\nprocessing through the gateway's pipeline.\n", "operationId": "adminBundleStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" }, "description": "Bundle ID" } ], "responses": { "200": { "description": "Bundle status details", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/Base64Url43", "description": "Bundle transaction ID" }, "formatId": { "type": "integer", "description": "Format ID of the bundle" }, "unbundleFilterId": { "type": "integer", "description": "ID of the current unbundle filter configuration" }, "indexFilterId": { "type": "integer", "description": "ID of the current index filter configuration" }, "dataItemCount": { "type": "integer", "description": "Total number of data items in the bundle" }, "matchedDataItemCount": { "type": "integer", "description": "Number of data items matching filter criteria" }, "firstQueuedAt": { "type": "integer", "description": "Unix timestamp of first queue attempt" }, "lastQueuedAt": { "type": "integer", "description": "Unix timestamp of most recent queue attempt" }, "firstSkippedAt": { "type": "integer", "nullable": true, "description": "Unix timestamp of first skip, if any" }, "lastSkippedAt": { "type": "integer", "nullable": true, "description": "Unix timestamp of most recent skip, if any" }, "firstUnbundledAt": { "type": "integer", "description": "Unix timestamp when unbundling first started" }, "lastUnbundledAt": { "type": "integer", "description": "Unix timestamp when unbundling was last performed" }, "firstFullyIndexedAt": { "type": "integer", "description": "Unix timestamp when indexing first completed" }, "lastFullyIndexedAt": { "type": "integer", "description": "Unix timestamp when indexing was last completed" }, "rootTransactionId": { "$ref": "#/components/schemas/Base64Url43", "description": "Transaction ID of the root bundle" }, "importAttemptCount": { "type": "integer", "description": "Number of times bundle import was attempted" }, "duplicatedDataItemCount": { "type": "integer", "description": "Number of duplicate data items found" }, "previousUnbundleFilterId": { "type": "integer", "description": "ID of the previous unbundle filter configuration" }, "previousIndexFilterId": { "type": "integer", "description": "ID of the previous index filter configuration" }, "retryAttemptCount": { "type": "integer", "description": "Number of retry attempts" }, "firstRetriedAt": { "type": "integer", "description": "Unix timestamp of first retry attempt" }, "lastRetriedAt": { "type": "integer", "description": "Unix timestamp of most recent retry attempt" } }, "required": [ "id", "formatId", "unbundleFilterId", "indexFilterId", "dataItemCount", "matchedDataItemCount", "rootTransactionId", "importAttemptCount", "duplicatedDataItemCount" ] } } } }, "400": { "description": "Invalid bundle ID format", "content": { "text/plain": { "schema": { "type": "string", "example": "Must provide a valid bundle id" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Bundle not found", "content": { "text/plain": { "schema": { "type": "string", "example": "Bundle not found" } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ar-io/admin/block-data": { "put": { "tags": [ "Admin" ], "summary": "Blocks transactions or data-items so your AR.IO Gateway will not serve them.", "description": "Submits a TX ID/data-item ID or sha-256 content hash for content you do not want your AR.IO Gateway to serve. Once submitted, your Gateway will not respond to requests for these transactions or data-items.\n\n\nWARNING - Testing a TX ID here WILL result in that data being blocked by your Gateway.\n", "operationId": "adminBlockData", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "TX ID for a transaction you want to block." }, "notes": { "type": "string", "description": "Any notes or comments related to the block data. Documentation purposes only." }, "source": { "type": "string", "description": "The source from which the block data was obtained. Documentation purposes only." } } }, "examples": { "example1": { "value": { "id": "3lyxgbgEvqNSvJrTX2J7CfRychUD5KClFhhVLyTPNCQ", "notes": "This content is offensive", "source": "Public Block list" } } } } } }, "responses": { "200": { "description": "Successful operation." }, "401": { "description": "Unauthorized, API key likely incorrect." } }, "security": [ { "bearerAuth": [] } ] } }, "/ar-io/admin/block-name": { "put": { "tags": [ "Admin" ], "summary": "Blocks an ARNS name so your AR.IO Gateway will not serve it.", "description": "Blocks an ARNS name so your AR.IO Gateway will not serve it.", "operationId": "adminBlockName", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name you want to block." }, "notes": { "type": "string", "description": "Any notes or comments related to the block name. Documentation purposes only." }, "source": { "type": "string", "description": "The source from which the block name was obtained. Documentation purposes only." } } } } } }, "responses": { "200": { "description": "Successful operation." }, "401": { "description": "Unauthorized, API key likely incorrect." } }, "security": [ { "bearerAuth": [] } ] } }, "/ar-io/admin/unblock-name": { "put": { "tags": [ "Admin" ], "summary": "Unblock an ARNS name.", "description": "Unblock an ARNS name so your AR.IO Gateway will serve it again.", "operationId": "adminUnblockName", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name you want to unblock." } } } } } }, "responses": { "200": { "description": "Successful operation." }, "401": { "description": "Unauthorized, API key likely incorrect." } }, "security": [ { "bearerAuth": [] } ] } }, "/ar-io/admin/export-parquet": { "post": { "tags": [ "Admin" ], "summary": "Export data to Parquet format", "description": "Initiates an export of data to Parquet format files. This process runs in the background\nand exports data for the specified block height range.\n", "operationId": "adminExportParquet", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "outputDir": { "type": "string", "description": "Directory in the server where Parquet files will be saved" }, "startHeight": { "type": "integer", "minimum": 0, "description": "Starting block height for the export" }, "endHeight": { "type": "integer", "minimum": 0, "description": "Ending block height for the export" }, "maxFileRows": { "type": "integer", "minimum": 0, "description": "Maximum number of rows per Parquet file" } }, "required": [ "outputDir", "startHeight", "endHeight", "maxFileRows" ] } } } }, "responses": { "200": { "description": "Export process started successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Parquet export started" } } } } } }, "400": { "description": "Invalid parameters provided" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ar-io/admin/export-parquet/status": { "get": { "tags": [ "Admin" ], "summary": "Get Parquet export status", "description": "Returns the current status of the Parquet export process", "operationId": "adminExportParquetStatus", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Current export status", "content": { "application/json": { "schema": { "type": "object", "description": "Current status of the export process", "properties": { "status": { "type": "string", "enum": [ "not_started", "running", "completed", "errored" ], "description": "Current status of the export process" }, "outputDir": { "type": "string", "description": "Directory where Parquet files are being saved" }, "startHeight": { "type": "integer", "description": "Starting block height of the export" }, "endHeight": { "type": "integer", "description": "Ending block height of the export" }, "maxFileRows": { "type": "integer", "description": "Maximum number of rows per Parquet file" }, "durationInSeconds": { "type": "number", "description": "Duration of the export process in seconds" }, "endTime": { "type": "string", "format": "date-time", "description": "ISO timestamp when the export completed" }, "endTimestamp": { "type": "integer", "description": "Unix timestamp when the export completed" }, "error": { "type": "string", "description": "Error message if the export failed" } }, "required": [ "status" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ar-io/admin/prune-stable-data-items": { "post": { "tags": [ "Admin" ], "summary": "Prune stable data items", "description": "Removes stable data items from the database that were indexed before the specified timestamp.\nThis helps manage database size by removing older, stable data items.\n", "operationId": "adminPruneStableDataItems", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "indexedAtThreshold": { "type": "integer", "minimum": 0, "description": "Unix timestamp - data items indexed before this time will be pruned" } }, "required": [ "indexedAtThreshold" ] }, "example": { "indexedAtThreshold": 1677721600 } } } }, "responses": { "200": { "description": "Data items successfully pruned", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Stable data items pruned successfully" } } } } } }, "400": { "description": "Invalid indexedAtThreshold parameter", "content": { "text/plain": { "schema": { "type": "string", "example": "Invalid indexedAtThreshold - must be a positive integer" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ar-io/rate-limit/ip/{ip}": { "get": { "tags": [ "Rate Limiting" ], "summary": "Query IP bucket balance", "description": "Get the current rate limit token balance for an IP address. Returns both regular\n(refilling) and paid tokens. Buckets are created on first request and refill over time.\n\n**Token System:**\n- 1 token = 1 KiB (1,024 bytes)\n- Regular tokens: Automatically refill based on configured rate (e.g., 20 KB/s)\n- Paid tokens: Acquired via x402 payments, never refill, consumed after regular tokens\n", "operationId": "getRateLimitIpBalance", "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string", "format": "ipv4 or ipv6" }, "description": "IP address (IPv4, IPv6, or IPv4-mapped IPv6 format)", "example": "192.168.1.100" } ], "responses": { "200": { "description": "Successfully retrieved IP bucket balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP address", "example": "192.168.1.100" }, "tokens": { "type": "number", "description": "Regular tokens (refilling)", "example": 95000 }, "paidTokens": { "type": "number", "description": "Paid tokens (non-refilling)", "example": 50000 }, "capacity": { "type": "number", "description": "Maximum regular token capacity", "example": 100000 }, "refillRate": { "type": "number", "description": "Refill rate in tokens per second", "example": 20 }, "lastRefill": { "type": "number", "format": "int64", "description": "Last refill timestamp (Unix milliseconds)", "example": 1735689600000 } }, "required": [ "ip", "tokens", "paidTokens", "capacity", "refillRate", "lastRefill" ] } } } }, "400": { "description": "Invalid IP address format", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid IP address format" } } } } } }, "404": { "description": "Bucket not found (created on first request)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bucket not found" }, "message": { "type": "string", "example": "No rate limit bucket exists for this IP. Buckets are created on first request." } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Rate Limiting" ], "summary": "Top up IP bucket", "description": "Add paid tokens to an IP bucket via x402 payment or admin authentication.\n\n**Authentication Modes:**\n\n1. **x402 Payment (Public):**\n - Provide X-Payment header with payment data\n - Tokens calculated from payment amount\n - 10x capacity multiplier applied\n - Example: $0.10 payment → ~976 KB equivalent → ~976,000 tokens\n\n2. **Admin (Private/Testing):**\n - Provide Authorization: Bearer header with admin API key\n - Specify exact token count and type in request body\n - No multiplier applied (raw token count)\n - Only supports paid tokens currently\n", "operationId": "topUpRateLimitIpBucket", "parameters": [ { "name": "ip", "in": "path", "required": true, "schema": { "type": "string", "format": "ipv4 or ipv6" }, "description": "IP address", "example": "192.168.1.100" }, { "name": "X-Payment", "in": "header", "required": false, "schema": { "type": "string", "format": "base64" }, "description": "Base64-encoded x402 payment data (for x402 payment mode).\nMutually exclusive with Authorization header.\n" } ], "security": [ {}, { "bearerAuth": [] } ], "requestBody": { "description": "Required for admin authentication mode. Omit for x402 payment mode.\n", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "number", "minimum": 1, "description": "Number of tokens to add (admin mode only)", "example": 50000 }, "tokenType": { "type": "string", "enum": [ "paid" ], "description": "Type of tokens (admin mode only, currently only \"paid\" supported)", "example": "paid" } }, "required": [ "tokens", "tokenType" ] } } } }, "responses": { "200": { "description": "Successfully topped up IP bucket", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "example": "192.168.1.100" }, "tokens": { "type": "number", "example": 95000 }, "paidTokens": { "type": "number", "example": 150000 }, "capacity": { "type": "number", "example": 100000 }, "refillRate": { "type": "number", "example": 20 }, "lastRefill": { "type": "number", "format": "int64", "example": 1735689600000 }, "topUp": { "type": "object", "description": "Information about the top-up operation", "properties": { "tokensAdded": { "type": "number", "description": "Number of tokens added", "example": 100000 }, "paymentAmount": { "type": "string", "description": "Payment amount in USDC atomic units (x402 mode only)", "example": "1000000" }, "multiplierApplied": { "type": "number", "description": "Capacity multiplier applied (10 for x402, 1 for admin)", "example": 10 }, "tokenType": { "type": "string", "description": "Type of tokens added (admin mode only)", "example": "paid" } }, "required": [ "tokensAdded", "multiplierApplied" ] } } } } } }, "400": { "description": "Invalid IP format or invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Invalid tokens value" }, "message": { "type": "string", "example": "tokens must be a positive number" } } } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Provide X-Payment header for x402 payment or Authorization: Bearer header for admin access" } } } } } }, "402": { "description": "Payment verification or settlement failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment failed" }, "message": { "type": "string", "example": "Payment verification failed: insufficient amount" } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/ar-io/rate-limit/resource": { "get": { "tags": [ "Rate Limiting" ], "summary": "Query resource bucket balance", "description": "Get the current rate limit token balance for a specific resource (method + host + path combination).\nUseful for monitoring resource-specific usage.\n\n**Smart Defaults:**\n- `method`: Defaults to \"GET\" (most common)\n- `host`: Defaults to current request's Host header\n- `path`: Required parameter\n", "operationId": "getRateLimitResourceBalance", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Request path", "example": "/TX_ID" }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS" ], "default": "GET" }, "description": "HTTP method", "example": "GET" }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Host header (defaults to current request host)", "example": "gateway.example.com" } ], "responses": { "200": { "description": "Successfully retrieved resource bucket balance", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "example": "GET" }, "host": { "type": "string", "example": "gateway.example.com" }, "path": { "type": "string", "example": "/TX_ID" }, "tokens": { "type": "number", "description": "Regular tokens (refilling)", "example": 980000 }, "paidTokens": { "type": "number", "description": "Paid tokens (non-refilling)", "example": 100000 }, "capacity": { "type": "number", "description": "Maximum regular token capacity", "example": 1000000 }, "refillRate": { "type": "number", "description": "Refill rate in tokens per second", "example": 100 }, "lastRefill": { "type": "number", "format": "int64", "description": "Last refill timestamp (Unix milliseconds)", "example": 1735689600000 } }, "required": [ "method", "host", "path", "tokens", "paidTokens", "capacity", "refillRate", "lastRefill" ] } } } }, "400": { "description": "Missing path parameter or invalid method", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing required parameter: path" }, "validMethods": { "type": "array", "items": { "type": "string" }, "example": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS" ] } } } } } }, "404": { "description": "Bucket not found (created on first request)", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Bucket not found" }, "message": { "type": "string", "example": "No rate limit bucket exists for this resource. Buckets are created on first request." } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Rate Limiting" ], "summary": "Top up resource bucket", "description": "Add paid tokens to a resource bucket via x402 payment or admin authentication.\nUses same authentication modes as IP bucket top-up.\n\n**Resource Identification:**\n- Combination of method + host + path uniquely identifies a resource bucket\n- Smart defaults: method=GET, host=current request host\n", "operationId": "topUpRateLimitResourceBucket", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Request path", "example": "/TX_ID" }, { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS" ], "default": "GET" }, "description": "HTTP method", "example": "GET" }, { "name": "host", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Host header (defaults to current request host)", "example": "gateway.example.com" }, { "name": "X-Payment", "in": "header", "required": false, "schema": { "type": "string", "format": "base64" }, "description": "Base64-encoded x402 payment data (for x402 payment mode)" } ], "security": [ {}, { "bearerAuth": [] } ], "requestBody": { "description": "Required for admin authentication mode. Omit for x402 payment mode.", "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "number", "minimum": 1, "description": "Number of tokens to add (admin mode only)", "example": 50000 }, "tokenType": { "type": "string", "enum": [ "paid" ], "description": "Type of tokens (admin mode only)", "example": "paid" } }, "required": [ "tokens", "tokenType" ] } } } }, "responses": { "200": { "description": "Successfully topped up resource bucket", "content": { "application/json": { "schema": { "type": "object", "properties": { "method": { "type": "string", "example": "GET" }, "host": { "type": "string", "example": "gateway.example.com" }, "path": { "type": "string", "example": "/TX_ID" }, "tokens": { "type": "number", "example": 980000 }, "paidTokens": { "type": "number", "example": 150000 }, "capacity": { "type": "number", "example": 1000000 }, "refillRate": { "type": "number", "example": 100 }, "lastRefill": { "type": "number", "format": "int64", "example": 1735689600000 }, "topUp": { "type": "object", "properties": { "tokensAdded": { "type": "number", "example": 100000 }, "paymentAmount": { "type": "string", "example": "1000000" }, "multiplierApplied": { "type": "number", "example": 10 }, "tokenType": { "type": "string", "example": "paid" } }, "required": [ "tokensAdded", "multiplierApplied" ] } } } } } }, "400": { "description": "Missing parameters or invalid request body", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Missing required parameter: path" }, "validMethods": { "type": "array", "items": { "type": "string" }, "example": [ "GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS" ] } } } } } }, "401": { "description": "Missing or invalid authentication", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Unauthorized" }, "message": { "type": "string", "example": "Provide X-Payment header for x402 payment or Authorization: Bearer header for admin access" } } } } } }, "402": { "description": "Payment verification or settlement failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "Payment failed" }, "message": { "type": "string", "example": "Payment settlement failed: timeout" } } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/local/farcaster/frame/{txId}": { "get": { "tags": [ "Farcaster Frames" ], "summary": "Handle a Farcaster initial Frame request.", "description": "Responds to a Farcaster initial Frame GET request by returning the content of a specified Arweave transaction or data item.", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } }, "post": { "tags": [ "Farcaster Frames" ], "summary": "Handle a Farcaster response Frame request.", "description": "Responds to a Farcaster response Frame POST request by returning the content of a specified Arweave transaction or data item.", "parameters": [ { "name": "txId", "in": "path", "required": true, "schema": { "$ref": "#/components/schemas/Base64Url43" } } ], "responses": { "200": { "description": "Successful operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" } } } } } } } } }