{ "openapi": "3.0.3", "info": { "title": "Atlantic API", "version": "0.1.0" }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "api-key" } }, "schemas": {} }, "paths": { "/is-alive": { "get": { "summary": "Be alive or not be alive", "tags": [ "Health check" ], "description": "Is alive", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "alive": { "type": "boolean" } }, "required": [ "alive" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {} }, "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {} }, "additionalProperties": false } } } } } } }, "/atlantic-query/{atlanticQueryId}": { "get": { "summary": "Get Atlantic Query", "tags": [ "Atlantic Query" ], "description": "Get the details of a Atlantic Query", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "atlanticQueryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticQuery": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "dedupId": { "type": "string", "nullable": true }, "transactionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "RECEIVED", "DONE", "FAILED", "IN_PROGRESS" ] }, "step": { "type": "string", "nullable": true }, "programHash": { "type": "string", "nullable": true }, "integrityFactHash": { "type": "string", "nullable": true }, "sharpFactHash": { "type": "string", "nullable": true }, "layout": { "type": "string", "nullable": true }, "isFactMocked": { "type": "boolean", "nullable": true }, "isProofMocked": { "type": "boolean", "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ], "nullable": true }, "jobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "declaredJobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "cairoVm": { "type": "string", "enum": [ "rust", "python" ] }, "cairoVersion": { "type": "string", "enum": [ "cairo0", "cairo1" ] }, "steps": { "type": "array", "items": { "type": "string" } }, "result": { "type": "string", "enum": [ "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION_ON_L1", "PROOF_VERIFICATION_ON_L2", "PROOF_VERIFICATION_ON_APE_CHAIN", "PROOF_VERIFICATION_ON_WORLD_CHAIN" ], "nullable": true }, "network": { "type": "string", "enum": [ "MAINNET", "TESTNET" ], "nullable": true }, "hints": { "type": "string", "enum": [ "herodotus_evm_grower", "herodotus_sn_grower" ], "nullable": true }, "sharpProver": { "type": "string", "enum": [ "stone", "stwo" ], "nullable": true }, "errorReason": { "type": "string", "nullable": true }, "submittedByClient": { "type": "string", "nullable": true }, "projectId": { "type": "string", "nullable": true }, "submittedByWallet": { "type": "string", "maxLength": 64, "nullable": true }, "bucketId": { "type": "string", "nullable": true }, "bucketJobIndex": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "customerName": { "type": "string", "nullable": true }, "isJobSizeValid": { "type": "boolean" }, "retryCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "client": { "type": "object", "properties": { "clientId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "isEmailVerified": { "type": "boolean" }, "image": { "type": "string", "nullable": true } }, "required": [ "clientId", "name", "isEmailVerified" ], "additionalProperties": false, "nullable": true }, "isRetriable": { "type": "boolean" }, "retryBlockedReason": { "type": "string", "enum": [ "NON_RETRIABLE_ERROR", "MAX_RETRIES_REACHED", "QUERY_NOT_FAILED" ], "nullable": true } }, "required": [ "id", "externalId", "dedupId", "transactionId", "status", "step", "programHash", "integrityFactHash", "sharpFactHash", "layout", "isFactMocked", "isProofMocked", "chain", "jobSize", "declaredJobSize", "cairoVm", "cairoVersion", "steps", "result", "network", "hints", "sharpProver", "errorReason", "submittedByClient", "projectId", "submittedByWallet", "bucketId", "bucketJobIndex", "customerName", "isJobSizeValid", "retryCount", "createdAt", "completedAt", "client", "isRetriable", "retryBlockedReason" ], "additionalProperties": false }, "metadataUrls": { "type": "array", "items": { "type": "string" } } }, "required": [ "atlanticQuery", "metadataUrls" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "ATLANTIC_QUERY_NOT_FOUND" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/atlantic-query-by-dedup-id": { "get": { "summary": "Get Atlantic Query by Dedup ID", "tags": [ "Atlantic Query" ], "description": "Get the details of an Atlantic Query by its dedup ID. Provide your API key for authorization.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "dedupId", "required": true }, { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticQuery": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "dedupId": { "type": "string", "nullable": true }, "transactionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "RECEIVED", "DONE", "FAILED", "IN_PROGRESS" ] }, "step": { "type": "string", "nullable": true }, "programHash": { "type": "string", "nullable": true }, "integrityFactHash": { "type": "string", "nullable": true }, "sharpFactHash": { "type": "string", "nullable": true }, "layout": { "type": "string", "nullable": true }, "isFactMocked": { "type": "boolean", "nullable": true }, "isProofMocked": { "type": "boolean", "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ], "nullable": true }, "jobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "declaredJobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "cairoVm": { "type": "string", "enum": [ "rust", "python" ] }, "cairoVersion": { "type": "string", "enum": [ "cairo0", "cairo1" ] }, "steps": { "type": "array", "items": { "type": "string" } }, "result": { "type": "string", "enum": [ "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION_ON_L1", "PROOF_VERIFICATION_ON_L2", "PROOF_VERIFICATION_ON_APE_CHAIN", "PROOF_VERIFICATION_ON_WORLD_CHAIN" ], "nullable": true }, "network": { "type": "string", "enum": [ "MAINNET", "TESTNET" ], "nullable": true }, "hints": { "type": "string", "enum": [ "herodotus_evm_grower", "herodotus_sn_grower" ], "nullable": true }, "sharpProver": { "type": "string", "enum": [ "stone", "stwo" ], "nullable": true }, "errorReason": { "type": "string", "nullable": true }, "submittedByClient": { "type": "string", "nullable": true }, "projectId": { "type": "string", "nullable": true }, "submittedByWallet": { "type": "string", "maxLength": 64, "nullable": true }, "bucketId": { "type": "string", "nullable": true }, "bucketJobIndex": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "customerName": { "type": "string", "nullable": true }, "isJobSizeValid": { "type": "boolean" }, "retryCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "externalId", "dedupId", "transactionId", "status", "step", "programHash", "integrityFactHash", "sharpFactHash", "layout", "isFactMocked", "isProofMocked", "chain", "jobSize", "declaredJobSize", "cairoVm", "cairoVersion", "steps", "result", "network", "hints", "sharpProver", "errorReason", "submittedByClient", "projectId", "submittedByWallet", "bucketId", "bucketJobIndex", "customerName", "isJobSizeValid", "retryCount", "createdAt", "completedAt" ], "additionalProperties": false } }, "required": [ "atlanticQuery" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "MISSING_API_KEY" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "ATLANTIC_QUERY_NOT_FOUND" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/atlantic-queries": { "get": { "summary": "Get the list of Atlantic queries you have submitted.", "tags": [ "Atlantic Query" ], "description": "Provide your API key to get list of Atlantic queries you have submitted.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "offset", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "search", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "clientId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "network", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "result", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticQueries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "dedupId": { "type": "string", "nullable": true }, "transactionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "RECEIVED", "DONE", "FAILED", "IN_PROGRESS" ] }, "step": { "type": "string", "nullable": true }, "programHash": { "type": "string", "nullable": true }, "integrityFactHash": { "type": "string", "nullable": true }, "sharpFactHash": { "type": "string", "nullable": true }, "layout": { "type": "string", "nullable": true }, "isFactMocked": { "type": "boolean", "nullable": true }, "isProofMocked": { "type": "boolean", "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ], "nullable": true }, "jobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "declaredJobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "cairoVm": { "type": "string", "enum": [ "rust", "python" ] }, "cairoVersion": { "type": "string", "enum": [ "cairo0", "cairo1" ] }, "steps": { "type": "array", "items": { "type": "string" } }, "result": { "type": "string", "enum": [ "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION_ON_L1", "PROOF_VERIFICATION_ON_L2", "PROOF_VERIFICATION_ON_APE_CHAIN", "PROOF_VERIFICATION_ON_WORLD_CHAIN" ], "nullable": true }, "network": { "type": "string", "enum": [ "MAINNET", "TESTNET" ], "nullable": true }, "hints": { "type": "string", "enum": [ "herodotus_evm_grower", "herodotus_sn_grower" ], "nullable": true }, "sharpProver": { "type": "string", "enum": [ "stone", "stwo" ], "nullable": true }, "errorReason": { "type": "string", "nullable": true }, "submittedByClient": { "type": "string", "nullable": true }, "projectId": { "type": "string", "nullable": true }, "submittedByWallet": { "type": "string", "maxLength": 64, "nullable": true }, "bucketId": { "type": "string", "nullable": true }, "bucketJobIndex": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "customerName": { "type": "string", "nullable": true }, "isJobSizeValid": { "type": "boolean" }, "retryCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "client": { "type": "object", "properties": { "clientId": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "isEmailVerified": { "type": "boolean" }, "image": { "type": "string", "nullable": true } }, "required": [ "clientId", "name", "isEmailVerified" ], "additionalProperties": false, "nullable": true }, "isRetriable": { "type": "boolean" }, "retryBlockedReason": { "type": "string", "enum": [ "NON_RETRIABLE_ERROR", "MAX_RETRIES_REACHED", "QUERY_NOT_FAILED" ], "nullable": true } }, "required": [ "id", "externalId", "dedupId", "transactionId", "status", "step", "programHash", "integrityFactHash", "sharpFactHash", "layout", "isFactMocked", "isProofMocked", "chain", "jobSize", "declaredJobSize", "cairoVm", "cairoVersion", "steps", "result", "network", "hints", "sharpProver", "errorReason", "submittedByClient", "projectId", "submittedByWallet", "bucketId", "bucketJobIndex", "customerName", "isJobSizeValid", "retryCount", "createdAt", "completedAt", "client", "isRetriable", "retryBlockedReason" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "atlanticQueries", "total" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "MISSING_API_KEY" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/atlantic-query-jobs/{atlanticQueryId}": { "get": { "summary": "Get the Atlantic query jobs for a given Atlantic query", "tags": [ "Atlantic Query" ], "description": "Provide the Atlantic query id to get the jobs for a given Atlantic query.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "atlanticQueryId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "atlanticQueryId": { "type": "string" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "COMPLETED", "FAILED" ] }, "jobName": { "type": "string", "enum": [ "TRACE_AND_METADATA_GENERATION", "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION", "FACT_HASH_REGISTRATION", "PROOF_GENERATION_AND_VERIFICATION", "TRANSFER_FACT_HASH_TO_WORLD_CHAIN" ] }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "context": {} }, "required": [ "id", "atlanticQueryId", "status", "jobName", "createdAt", "completedAt" ], "additionalProperties": false } }, "steps": { "type": "array", "items": { "type": "string" } } }, "required": [ "jobs", "steps" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/atlantic-queries/stats": { "get": { "summary": "Get the stats of Atlantic queries you have submitted.", "tags": [ "Atlantic Query" ], "description": "Provide your API key to get stats (average query time and total queries) of Atlantic queries you have submitted.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "averageProcessingTime": { "type": "number" }, "totalQueries": { "type": "number" } }, "required": [ "averageProcessingTime", "totalQueries" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "ATLANTIC_QUERY_NOT_FOUND" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/atlantic-queries/{atlanticQueryId}/retry": { "post": { "summary": "Retry a failed Atlantic query.", "tags": [ "Atlantic Query" ], "description": "Retry a failed Atlantic query. Only retriable errors can be retried. Maximum 3 retry attempts per query.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false }, { "schema": { "type": "string" }, "in": "path", "name": "atlanticQueryId", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticQuery": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "dedupId": { "type": "string", "nullable": true }, "transactionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "RECEIVED", "DONE", "FAILED", "IN_PROGRESS" ] }, "step": { "type": "string", "nullable": true }, "programHash": { "type": "string", "nullable": true }, "integrityFactHash": { "type": "string", "nullable": true }, "sharpFactHash": { "type": "string", "nullable": true }, "layout": { "type": "string", "nullable": true }, "isFactMocked": { "type": "boolean", "nullable": true }, "isProofMocked": { "type": "boolean", "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ], "nullable": true }, "jobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "declaredJobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "cairoVm": { "type": "string", "enum": [ "rust", "python" ] }, "cairoVersion": { "type": "string", "enum": [ "cairo0", "cairo1" ] }, "steps": { "type": "array", "items": { "type": "string" } }, "result": { "type": "string", "enum": [ "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION_ON_L1", "PROOF_VERIFICATION_ON_L2", "PROOF_VERIFICATION_ON_APE_CHAIN", "PROOF_VERIFICATION_ON_WORLD_CHAIN" ], "nullable": true }, "network": { "type": "string", "enum": [ "MAINNET", "TESTNET" ], "nullable": true }, "hints": { "type": "string", "enum": [ "herodotus_evm_grower", "herodotus_sn_grower" ], "nullable": true }, "sharpProver": { "type": "string", "enum": [ "stone", "stwo" ], "nullable": true }, "errorReason": { "type": "string", "nullable": true }, "submittedByClient": { "type": "string", "nullable": true }, "projectId": { "type": "string", "nullable": true }, "submittedByWallet": { "type": "string", "maxLength": 64, "nullable": true }, "bucketId": { "type": "string", "nullable": true }, "bucketJobIndex": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "customerName": { "type": "string", "nullable": true }, "isJobSizeValid": { "type": "boolean" }, "retryCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "externalId", "dedupId", "transactionId", "status", "step", "programHash", "integrityFactHash", "sharpFactHash", "layout", "isFactMocked", "isProofMocked", "chain", "jobSize", "declaredJobSize", "cairoVm", "cairoVersion", "steps", "result", "network", "hints", "sharpProver", "errorReason", "submittedByClient", "projectId", "submittedByWallet", "bucketId", "bucketJobIndex", "customerName", "isJobSizeValid", "retryCount", "createdAt", "completedAt" ], "additionalProperties": false }, "message": { "type": "string", "enum": [ "Query retry initiated" ] } }, "required": [ "atlanticQuery", "message" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "QUERY_NOT_RETRIABLE", "MAX_RETRIES_REACHED" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "FORBIDDEN" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "ATLANTIC_QUERY_NOT_FOUND" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "QUERY_NOT_IN_FAILED_STATUS" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/buckets": { "post": { "summary": "Create a new Atlantic bucket.", "tags": [ "Applicative Recursion" ], "description": "Create a new Atlantic bucket.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "nullable": true, "default": null }, "nodeWidth": { "type": "number", "nullable": true, "default": null }, "aggregatorVersion": { "type": "string", "enum": [ "snos_aggregator_0.13.3", "snos_aggregator_0.13.4", "snos_aggregator_0.14.0", "snos_aggregator_0.14.1" ] }, "aggregatorParams": { "type": "object", "additionalProperties": {}, "nullable": true, "default": null }, "mockProof": { "type": "boolean", "nullable": true, "default": false } }, "required": [ "aggregatorVersion" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticBucket": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "OPEN", "IN_PROGRESS", "DONE", "FAILED" ] }, "aggregatorVersion": { "type": "string", "enum": [ "snos_aggregator_0.13.3", "snos_aggregator_0.13.4", "snos_aggregator_0.14.0", "snos_aggregator_0.14.1" ] }, "aggregatorParams": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array" } ], "nullable": true }, "nodeWidth": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "leaves": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ] }, "mockProof": { "type": "boolean", "nullable": true }, "projectId": { "type": "string" }, "createdByClient": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "status", "aggregatorVersion", "aggregatorParams", "nodeWidth", "leaves", "chain", "mockProof", "projectId", "createdByClient", "createdAt" ], "additionalProperties": false } }, "required": [ "atlanticBucket" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "MISSING_API_KEY" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } }, "get": { "summary": "Get the list of buckets you have submitted.", "tags": [ "Applicative Recursion" ], "description": "Provide your API key to get list of buckets you have submitted.", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "number" }, "in": "query", "name": "offset", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "OPEN", "IN_PROGRESS", "DONE", "FAILED" ] }, "aggregatorVersion": { "type": "string", "enum": [ "snos_aggregator_0.13.3", "snos_aggregator_0.13.4", "snos_aggregator_0.14.0", "snos_aggregator_0.14.1" ] }, "aggregatorParams": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array" } ], "nullable": true }, "nodeWidth": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "leaves": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ] }, "mockProof": { "type": "boolean", "nullable": true }, "projectId": { "type": "string" }, "createdByClient": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "status", "aggregatorVersion", "aggregatorParams", "nodeWidth", "leaves", "chain", "mockProof", "projectId", "createdByClient", "createdAt" ], "additionalProperties": false } }, "total": { "type": "number" } }, "required": [ "data", "total" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "MISSING_API_KEY" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/buckets/close": { "post": { "tags": [ "Applicative Recursion" ], "description": "Close a bucket - after closing, you can no longer submit jobs to it", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "bucketId", "required": true } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticBucket": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "OPEN", "IN_PROGRESS", "DONE", "FAILED" ] }, "aggregatorVersion": { "type": "string", "enum": [ "snos_aggregator_0.13.3", "snos_aggregator_0.13.4", "snos_aggregator_0.14.0", "snos_aggregator_0.14.1" ] }, "aggregatorParams": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array" } ], "nullable": true }, "nodeWidth": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "leaves": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ] }, "mockProof": { "type": "boolean", "nullable": true }, "projectId": { "type": "string" }, "createdByClient": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "status", "aggregatorVersion", "aggregatorParams", "nodeWidth", "leaves", "chain", "mockProof", "projectId", "createdByClient", "createdAt" ], "additionalProperties": false } }, "required": [ "atlanticBucket" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "MISSING_API_KEY", "BUCKET_ALREADY_CLOSED" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "UNAUTHORIZED" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "BUCKET_NOT_FOUND" ] } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/buckets/{bucketId}": { "get": { "summary": "Get the details of a bucket.", "tags": [ "Applicative Recursion" ], "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "bucketId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "bucket": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "OPEN", "IN_PROGRESS", "DONE", "FAILED" ] }, "aggregatorVersion": { "type": "string", "enum": [ "snos_aggregator_0.13.3", "snos_aggregator_0.13.4", "snos_aggregator_0.14.0", "snos_aggregator_0.14.1" ] }, "aggregatorParams": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "enum": [ "null" ], "nullable": true } ] }, { "type": "object", "additionalProperties": {} }, { "type": "array" } ], "nullable": true }, "nodeWidth": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "leaves": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ] }, "mockProof": { "type": "boolean", "nullable": true }, "projectId": { "type": "string" }, "createdByClient": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "externalId", "status", "aggregatorVersion", "aggregatorParams", "nodeWidth", "leaves", "chain", "mockProof", "projectId", "createdByClient", "createdAt" ], "additionalProperties": false }, "queries": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "externalId": { "type": "string", "nullable": true }, "dedupId": { "type": "string", "nullable": true }, "transactionId": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "RECEIVED", "DONE", "FAILED", "IN_PROGRESS" ] }, "step": { "type": "string", "nullable": true }, "programHash": { "type": "string", "nullable": true }, "integrityFactHash": { "type": "string", "nullable": true }, "sharpFactHash": { "type": "string", "nullable": true }, "layout": { "type": "string", "nullable": true }, "isFactMocked": { "type": "boolean", "nullable": true }, "isProofMocked": { "type": "boolean", "nullable": true }, "chain": { "type": "string", "enum": [ "L1", "L2", "APE_CHAIN", "OFFCHAIN", "WORLD_CHAIN" ], "nullable": true }, "jobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "declaredJobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "nullable": true }, "cairoVm": { "type": "string", "enum": [ "rust", "python" ] }, "cairoVersion": { "type": "string", "enum": [ "cairo0", "cairo1" ] }, "steps": { "type": "array", "items": { "type": "string" } }, "result": { "type": "string", "enum": [ "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION_ON_L1", "PROOF_VERIFICATION_ON_L2", "PROOF_VERIFICATION_ON_APE_CHAIN", "PROOF_VERIFICATION_ON_WORLD_CHAIN" ], "nullable": true }, "network": { "type": "string", "enum": [ "MAINNET", "TESTNET" ], "nullable": true }, "hints": { "type": "string", "enum": [ "herodotus_evm_grower", "herodotus_sn_grower" ], "nullable": true }, "sharpProver": { "type": "string", "enum": [ "stone", "stwo" ], "nullable": true }, "errorReason": { "type": "string", "nullable": true }, "submittedByClient": { "type": "string", "nullable": true }, "projectId": { "type": "string", "nullable": true }, "submittedByWallet": { "type": "string", "maxLength": 64, "nullable": true }, "bucketId": { "type": "string", "nullable": true }, "bucketJobIndex": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647, "nullable": true }, "customerName": { "type": "string", "nullable": true }, "isJobSizeValid": { "type": "boolean" }, "retryCount": { "type": "integer", "minimum": -2147483648, "maximum": 2147483647 }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "externalId", "dedupId", "transactionId", "status", "step", "programHash", "integrityFactHash", "sharpFactHash", "layout", "isFactMocked", "isProofMocked", "chain", "jobSize", "declaredJobSize", "cairoVm", "cairoVersion", "steps", "result", "network", "hints", "sharpProver", "errorReason", "submittedByClient", "projectId", "submittedByWallet", "bucketId", "bucketJobIndex", "customerName", "isJobSizeValid", "retryCount", "createdAt", "completedAt" ], "additionalProperties": false } } }, "required": [ "bucket", "queries" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/atlantic-query": { "post": { "summary": "Submit a Atlantic query", "tags": [ "Atlantic Query" ], "description": "Submit a Atlantic query. You can choose to just generate a proof or generate and verify a proof. You can also choose to use a program file + input file (we will compute trace generation for you) or a pie file.", "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "externalId": { "type": "string", "description": "The external id of the query, you can use it to track the query", "default": "" }, "dedupId": { "type": "string", "description": "The dedup id of the query", "nullable": true, "default": null }, "sharpProver": { "type": "string", "enum": [ "stone", "stwo" ], "default": "stone", "description": "The prover to use for the proof generation" }, "layout": { "type": "string", "enum": [ "auto", "plain", "recursive", "recursive_with_poseidon", "recursive_large_output", "all_solidity", "all_cairo", "dynamic", "small", "dex", "starknet", "starknet_with_keccak" ], "default": "auto" }, "cairoVm": { "type": "string", "enum": [ "rust", "python" ], "default": "rust" }, "cairoVersion": { "type": "string", "enum": [ "cairo0", "cairo1" ], "default": "cairo0" }, "result": { "type": "string", "enum": [ "TRACE_GENERATION", "PROOF_GENERATION", "PROOF_VERIFICATION_ON_L1", "PROOF_VERIFICATION_ON_L2", "PROOF_VERIFICATION_ON_APE_CHAIN", "PROOF_VERIFICATION_ON_WORLD_CHAIN" ], "description": "Describe what you want to achieve", "default": "PROOF_GENERATION" }, "mockFactHash": { "type": "string", "enum": [ "false", "true" ], "description": "Used for proof verification, if true, a fact hash will be mocked", "default": "false" }, "network": { "type": "string", "enum": [ "MAINNET", "TESTNET" ], "default": "TESTNET" }, "hints": { "anyOf": [ { "type": "string", "enum": [ "herodotus_evm_grower", "herodotus_sn_grower" ] }, { "type": "string", "enum": [ "" ] } ] }, "declaredJobSize": { "type": "string", "enum": [ "XS", "S", "M", "L" ], "description": "Smaller jobs are cheaper, however your job might fail if you choose a job size that is too small." }, "programHash": { "type": "string", "description": "To use the program you are interested in, you must first register it. Registration occurs when you upload the program file for the first time.", "default": "" }, "programFile": { "type": "string", "format": "binary" }, "inputFile": { "type": "string", "format": "binary" }, "pieFile": { "type": "string", "format": "binary" }, "proofFile": { "type": "string", "format": "binary" }, "bucketId": { "type": "string", "nullable": true, "description": "(Applicative Recursion) The id of the bucket you want to submit the query to", "default": "" }, "bucketJobIndex": { "type": "number", "nullable": true, "description": "(Applicative Recursion) The index of the job inside the bucket", "default": null } }, "required": [ "declaredJobSize" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "apiKey", "required": false } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "atlanticQueryId": { "type": "string" } }, "required": [ "atlanticQueryId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "MISSING_API_KEY", "EMAIL_NOT_VERIFIED", "PROGRAM_FILE_SHOULD_BE_JSON", "PROOF_FILE_SHOULD_BE_JSON", "INPUT_FILE_FOR_CAIRO0_SHOULD_BE_JSON", "INPUT_FILE_FOR_CAIRO1_SHOULD_BE_TXT", "INPUT_FILE_SHOULD_BE_JSON_OR_TXT", "PIE_FILE_SHOULD_BE_ZIP", "INVALID_FILE_MIME_TYPE", "ZOD_INVALID_BODY_STRING", "MISSING_BUCKET_JOB_INDEX", "ATLANTIC_BUCKET_JOB_ALREADY_EXISTS", "ATLANTIC_QUERY_WITH_DEDUP_ID_ALREADY_EXISTS", "CHAIN_NOT_SUPPORT_PROOF_VERIFICATION", "STWO_NOT_SUPPORTED_FOR_CHAIN", "CHAIN_IS_REQUIRED_FOR_PROOF_VERIFICATION", "PROGRAM_FILE_OR_PIE_FILE_OR_PROGRAM_HASH_IS_REQUIRED", "PROGRAM_NOT_FOUND", "CAIRO1_IS_NOT_SUPPORTED_FOR_PYTHON", "INPUT_FILE_IS_NOT_SUPPORTED_FOR_CAIRO0_AND_RUST_VM", "INVALID_LAYOUT_FOR_PROOF_VERIFICATION_ON_INTEGRITY_L2", "INVALID_AGGREGATOR_FOR_VM", "INSUFFICIENT_CREDITS", "EXCEEDED_CREDITS_LIMIT" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "INVALID_API_KEY" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentRequired": { "type": "object", "properties": { "x402Version": { "type": "number", "enum": [ 2 ] }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "enum": [ "exact" ] }, "network": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string" }, "amount": { "type": "string" }, "resource": { "type": "string" }, "statement": { "type": "string" }, "mimeType": { "type": "string" }, "maxTimeoutSeconds": { "type": "number" }, "extra": { "type": "object", "additionalProperties": {} } }, "required": [ "scheme", "network", "asset", "payTo", "amount", "resource", "mimeType" ], "additionalProperties": false } }, "error": { "type": "string" } }, "required": [ "x402Version", "accepts", "error" ], "additionalProperties": false }, "paymentRequiredHeader": { "type": "string" } }, "required": [ "paymentRequired", "paymentRequiredHeader" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "BUCKET_NOT_FOUND" ] } }, "required": [ "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR", "ZOD_PARSING_ERROR" ] } }, "required": [ "message" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://atlantic.api.herodotus.cloud", "description": "Production" }, { "url": "https://stg.atlantic.api.herodotus.cloud", "description": "Staging" } ] }