# Herodotus Cloud Services

Canonical docs base URL: https://docs.herodotus.cloud

Use this file to route LLMs to the right Herodotus docs quickly.
All URLs below resolve under `https://docs.herodotus.cloud`.

Primary links (from docs config):
- Website / Console: https://herodotus.cloud
- Console: https://www.herodotus.cloud/en/login
- Support: mailto:hello@herodotus.dev
- GitHub: https://github.com/HerodotusDev
- Twitter / X: https://x.com/HerodotusCloud
- LinkedIn: https://www.linkedin.com/company/herodotus
- Company Website: https://herodotus.dev
- In-Depth Company Docs: https://docs.herodotus.dev/
- Additional Storage Proofs Docs: https://docs.storageproofs.com/

## How to use this file (for LLMs)

- Prefer answering from the linked pages directly; do not infer undocumented behavior.
- If a question is API-shape specific, prioritize endpoint pages and OpenAPI files.
- If a question is architecture/concepts specific, prioritize concept pages before endpoint pages.
- Each product has a matching AI Skill — a vendor-neutral playbook for building with that product. Read the skill before starting implementation work.
- The **Herodotus Full Stack AI Skill** is the recommended starting point — it covers the full product stack and helps pick the right products.
- If unsure, start from the "Start here" link for that product, then drill down.

## AI Skills — open source repository

All Herodotus AI skills are maintained in a dedicated open-source repo:
- GitHub: https://github.com/HerodotusDev/ai-skills
- Install: `curl -fsSL https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/install.sh | bash`
  (interactive selector — auto-detects installed tools and lets users pick which to set up)

Supports: Claude Code, Cursor, Codex, Google Gemini/Jules, Antigravity.
Skills install under a `herodotus/` parent folder (e.g. `.cursor/skills/herodotus/atlantic-api/SKILL.md`).

### Install per tool (skip interactive selector)

- Claude Code (installer, global): `curl -fsSL .../install.sh | bash -s -- --claude`
- Claude Code (installer, project-local): `curl -fsSL .../install.sh | bash -s -- --claude --project`
- Claude Code (inside app): `/plugin marketplace add HerodotusDev/ai-skills` then `/plugin install herodotus-skills@herodotus`
- Claude Code (CLI): `claude plugin marketplace add HerodotusDev/ai-skills` then `claude plugin install herodotus-skills@herodotus`
- Cursor: `curl -fsSL .../install.sh | bash -s -- --cursor` (global) or `--cursor --project` (project-local)
- Codex: `curl -fsSL .../install.sh | bash -s -- --codex` (global) or `--codex --project` (project-local)
- Google Gemini/Jules: `curl -fsSL .../install.sh | bash -s -- --google`
- Antigravity: `curl -fsSL .../install.sh | bash -s -- --antigravity` (global) or `--antigravity --project`

### Available skills

| Skill | Raw URL | Use when |
|-------|---------|----------|
| Herodotus (Full Stack) | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus/SKILL.md | Start here — full stack overview, product selection, cross-product patterns |
| Atlantic API | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/atlantic-api/SKILL.md | Cairo proving jobs, lifecycle, artifacts |
| Data Processor | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor/SKILL.md | HDP modules, soundness, dry-run/fetch-proofs/sound-run |
| Data Processor API | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-processor-api/SKILL.md | Task/module orchestration via HTTP |
| Storage Proof API | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/storage-proof-api/SKILL.md | Proof requests, Satellite readback |
| Satellite Contracts | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/satellite-contracts/SKILL.md | ISatellite integration, safe reads |
| Data Structure Indexer API | https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/data-structure-indexer-api/SKILL.md | Accumulator/remapper discovery |

## Intent routing (fast)

- New user onboarding -> /documentation/introduction, /documentation/quickstart, /documentation/authentication
- Full stack overview and product selection -> /skills/herodotus (skill) or https://raw.githubusercontent.com/HerodotusDev/ai-skills/main/plugins/herodotus-skills/skills/herodotus/SKILL.md
- Submit and monitor STARK proving jobs (Atlantic) -> /atlantic-api/getting-started, /atlantic-api/sending-query, /atlantic-api/status — skill: /skills/atlantic-api
- Understand proving pipeline stages -> /atlantic-api/steps/trace-generation, /atlantic-api/steps/proof-generation, /atlantic-api/steps/l1-proof-verification, /atlantic-api/steps/l2-proof-verification
- Use HDP locally or with proving -> /data-processor/cli-installation, /data-processor/running-hdp, /data-processor/proving — skill: /skills/data-processor
- Build HDP modules and reason about soundness -> /data-processor/architecture, /data-processor/pipeline, /data-processor/verification, /data-processor/design-patterns
- Orchestrate tasks/modules via server API -> /data-processor-api/introduction and pages in "Data Processor API" below — skill: /skills/data-processor-api
- Storage proofs and on-chain consumption -> /storage-proofs-api/introduction, /storage-proofs-api/key-concepts, /storage-proofs-api/contracts/accessing-data — skill: /skills/storage-proof-api
- Satellite contracts architecture/integration -> /satellite-contracts/introduction, /satellite-contracts/architecture, /satellite-contracts/deployments-and-integration — skill: /skills/satellite-contracts
- Data Structure Indexer API overview -> /data-structure-indexer-api/introduction — skill: /skills/data-structure-indexer-api
- Skill selection and implementation playbooks -> /skills/index, /skills/how-to-use
- Install AI skills for coding tools -> https://github.com/HerodotusDev/ai-skills

## Product map and start points

- Core docs (onboarding/auth): /documentation/introduction
- Atlantic API (managed proving): /atlantic-api/introduction
- Data Processor / HDP (module execution + proving flow): /data-processor/introduction
- Data Processor API (task/module orchestration): /data-processor-api/introduction
- Storage Proof API: /storage-proofs-api/introduction
- Satellite Contracts (on-chain verification/access patterns): /satellite-contracts/introduction
- Data Structure Indexer API: /data-structure-indexer-api/introduction
- AI Skills (implementation playbooks): /skills/index
- AI Skills GitHub repo: https://github.com/HerodotusDev/ai-skills

## Task-oriented reading paths

### Atlantic proving workflow
1) Introduction and setup:
- /atlantic-api/introduction
- /skills/atlantic-api
- /atlantic-api/getting-started
2) Query submission and lifecycle:
- /atlantic-api/sending-query
- /atlantic-api/status
- /atlantic-api/downloading-files
- /atlantic-api/webhooks
3) Verification and contracts:
- /atlantic-api/integrity-verifier
- /atlantic-api/dynamic
- /atlantic-api/contract-addresses
4) Operational details:
- /atlantic-api/pricing
- /atlantic-api/applicative-recursion
- /atlantic-api/examples

### HDP workflow
1) Install and run:
- /data-processor/cli-installation
- /data-processor/running-hdp
- /data-processor/proving
2) Understand internals:
- /data-processor/architecture
- /data-processor/pipeline
- /data-processor/capabilities
- /data-processor/verification
- /data-processor/state-management
- /data-processor/state-server
- /data-processor/output
3) Implement modules safely:
- /skills/data-processor
- /data-processor/eth-call
- /data-processor/design-patterns
- /data-processor/examples
4) Debug and reference:
- /data-processor/reference-cli
- /data-processor/reference-configuration
- /data-processor/reference-types
- /data-processor/debugging
- /data-processor/glossary
- /data-processor/documentation
- /data-processor/repository

## Complete page index

### Documentation
#### Get Started
- /documentation/introduction - Introduction. Welcome to Herodotus Cloud
- /documentation/quickstart - Quick Start. Get started with Herodotus Cloud Services in minutes
- /documentation/authentication - Authentication. How to authenticate with the Herodotus Cloud Services APIs

### AI Skills
#### AI Skills
- /skills/index - Overview. Central index of Herodotus vendor-neutral AI skill playbooks
- /skills/how-to-use - How to Use AI Skills. Practical guide for selecting, importing, and applying Herodotus AI skills
#### Skills
- /skills/herodotus - Herodotus Full Stack AI Skill. One skill to understand the entire stack, pick the right products, and compose cross-product workflows
- /skills/atlantic-api - Atlantic API AI Skill. Vendor-neutral AI playbook for building with Atlantic API safely and accurately
- /skills/data-processor - Data Processor AI Skill. Vendor-neutral AI playbook for building provable computation modules with HDP
- /skills/data-processor-api - Data Processor API AI Skill. Vendor-neutral AI playbook for HDP Server task and module orchestration
- /skills/storage-proof-api - Storage Proof API AI Skill. Vendor-neutral AI playbook for requesting, tracking, and consuming storage proofs
- /skills/satellite-contracts - Satellite Contracts AI Skill. Vendor-neutral AI playbook for integrating with Herodotus Satellite contracts
- /skills/data-structure-indexer-api - Data Structure Indexer API AI Skill. Vendor-neutral AI playbook for working with accumulators and remappers safely

### Atlantic API
#### Atlantic Prover Suite
- /atlantic-api/introduction - Introduction. Atlantic is a managed ZK Prover service that allows developers to easily integrate with StarkWare's SHARP
- /skills/atlantic-api - Atlantic API AI Skill (cross-referenced from Skills)
- /atlantic-api/getting-started - Getting Started. How to get started with the Atlantic API
- /atlantic-api/examples - Examples. Explore practical examples and code samples for integrating Atlantic STARK proving service
- /atlantic-api/sending-query - Sending Query. Prepare appropriate request body based on your input and desired outcome
- /atlantic-api/stwo - S-two. Learn about StarkWare's next-generation S-two prover and how Atlantic leverages it for high-performance proof generation
- /atlantic-api/status - Query Status. How to check the status of your Atlantic queries
- /atlantic-api/downloading-files - Downloading PIE & PROOF. How to download PIE and PROOF files from your Atlantic queries
- /atlantic-api/webhooks - Webhooks. Configure webhooks to receive real-time notifications about Atlantic query progress
- /atlantic-api/integrity-verifier - Integrity Verifier. Verify STARK proofs on Starknet and register verified proofs in Integrity's storage
- /atlantic-api/dynamic - Dynamic Layout on L2. Proof verification with Integrity using dynamic or all_cairo layouts
- /atlantic-api/contract-addresses - Contract Addresses. Smart contract addresses for Atlantic STARK proof verification on Ethereum, StarkNet, and other supported chains
- /atlantic-api/pricing - Pricing. Pricing for different services
- /atlantic-api/applicative-recursion - Applicative Recursion. Submit multiple queries to the same bucket and verify them together as a single on-chain operation
#### Atlantic Steps
- /atlantic-api/steps/trace-generation - Trace Generation. Running Cairo program on given inputs and generating pie.zip file
- /atlantic-api/steps/proof-generation - Proof Generation. Converting pie.zip into STARK proof (proof.json), verifiable at lower cost
- /atlantic-api/steps/l1-proof-verification - L1 Proof Verification. STARK proofs can be verified on L1 (Ethereum) via FactRegistry contract
- /atlantic-api/steps/l2-proof-verification - L2 Proof Verification. STARK proofs can be verified on L2 (Starknet) with Integrity verifier
#### Handy Links
- /atlantic-api/console - Console. Access the Herodotus Cloud Console to manage Atlantic API keys, monitor proof generation, and track usage
- /atlantic-api/swagger-ui - Swagger UI. Interactive API documentation and testing interface for Atlantic STARK proving service endpoints
#### Endpoints
- /atlantic-api/endpoints/submit-query - Submit query. Submit a Cairo program for STARK proof generation and optional on-chain verification via Atlantic API
- /atlantic-api/endpoints/get-query - Get query. Retrieve the status and details of a submitted Atlantic STARK proof query by its ID
- /atlantic-api/endpoints/get-query-by-dedup-id - Get query by dedup ID. Retrieve an Atlantic STARK proof query using your custom deduplication identifier
- /atlantic-api/endpoints/get-query-jobs - Get query jobs. Get detailed job information for an Atlantic proof generation query
- /atlantic-api/endpoints/list-queries - List queries. List all Atlantic STARK proof queries submitted with your API key with pagination support
- /atlantic-api/endpoints/is-alive - Is Alive. Check the health status and availability of the Atlantic API service
- /atlantic-api/endpoints/create-bucket - Create bucket
- /atlantic-api/endpoints/list-buckets - List buckets
- /atlantic-api/endpoints/get-bucket - Get bucket
- /atlantic-api/endpoints/close-bucket - Close bucket

### Data Processor
#### Data Processor (HDP)
- /data-processor/introduction - Introduction. What HDP is, why teams use it, and what it can (and cannot) prove
#### AI Skill
- /skills/data-processor - Data Processor AI Skill (cross-referenced from Skills)
#### Setup and Run
- /data-processor/cli-installation - CLI Installation and Usage. Install the HDP CLI and run your first HDP pipeline
- /data-processor/running-hdp - Ways to Run HDP. Local execution, Atlantic proving, and HDP Server orchestration
- /data-processor/proving - Proving with STWO. Generate STWO prover input from HDP sound-run
#### Core Concepts
- /data-processor/architecture - Architecture Overview. How Cairo1 modules, Cairo0 verification, and Rust handlers work together in HDP
- /data-processor/pipeline - Pipeline Stages. Dry run, fetch-proofs, and sound run end-to-end
- /data-processor/capabilities - HDP Capabilities and API Surface. Everything available through the HDP object in Cairo modules
- /data-processor/verification - Verification Model. How HDP verifies historical chain data before executing your module
- /data-processor/state-management - State Management. Memorizers, injected state, and unconstrained data in HDP
- /data-processor/state-server - State Server. Run and use the HDP state_server for injected state proofs
- /data-processor/output - Output Model. task_hash, output_root, and mmr_metas produced by HDP
#### Guides and Examples
- /data-processor/eth-call - Provable EVM Contract Calls. Using execute_eth_call to call EVM contracts at historical blocks inside HDP
- /data-processor/design-patterns - Design Patterns and Constraints. How to design sound HDP modules without overtrusting off-chain indexing
- /data-processor/examples - Official Examples by Use Case. What each hdp-cairo example demonstrates and which APIs it uses
#### Reference
- /data-processor/reference-cli - CLI Reference. Commands and flags for the HDP CLI
- /data-processor/reference-configuration - Configuration Reference. Environment variables and runtime configuration for HDP
- /data-processor/reference-types - Types Reference. Core HDP input/output and proof-related types
- /data-processor/debugging - Debugging. Common troubleshooting steps for HDP pipelines and Cairo modules
- /data-processor/glossary - Glossary. Core HDP terms
- /data-processor/documentation - Official HDP Documentation. Primary upstream docs for hdp-cairo
- /data-processor/repository - GitHub Repository. Source code, examples, and release history for HDP Cairo

### Data Processor API
#### HDP Server API
- /data-processor-api/introduction - Introduction. HDP Server API for scheduling and managing Data Processor tasks with Herodotus Atlantic proving service
- /data-processor-api/health-check - Health Check. Check the health status of the HDP server, database, and message queues
#### AI Skill
- /skills/data-processor-api - Data Processor API AI Skill (cross-referenced from Skills)
#### Tasks
- /data-processor-api/create-task - Schedule a new task. Create and submit a Data Processor task for verified custom module execution with onchain commitment
- /data-processor-api/list-tasks - List Tasks. Retrieve a paginated list of HDP tasks with optional search and filtering
- /data-processor-api/task-status - Get Task Status. Retrieve the current processing status and details of an HDP task by its UUID
- /data-processor-api/get-task-details - Get Task Details. Retrieve comprehensive details of an HDP task including all metadata and MMRs used
- /data-processor-api/get-mmrs - Get Used MMRs. Retrieve the list of MMRs (Merkle Mountain Ranges) used by a specific task
- /data-processor-api/get-task-output-preimage - Get Task Output Preimage. Retrieve the output tree root preimage for a specific HDP task
- /data-processor-api/retry-task - Retry Task. Retry a failed HDP task from the beginning or retry only decommitment for TaskDecommitmentFailed tasks
- /data-processor-api/decommitment-only - Decommitment Only. Submit a decommitment request for an HDP task when running HDP and generating PIE locally
- /data-processor-api/get-task-state-transitions - Get Task State Transitions. Retrieve the complete state transition history for a specific HDP task
#### Modules
- /data-processor-api/upload-module - Upload Module. Upload a new HDP module with compiled program, source code, and metadata
- /data-processor-api/list-modules - List Modules. Retrieve a list of HDP modules with optional filtering by marketplace or creator
- /data-processor-api/get-module - Get Module. Retrieve detailed information about a specific HDP module by its ID
- /data-processor-api/update-module - Update Module. Update metadata for an existing HDP module
- /data-processor-api/publish-module - Publish Module. Publish an HDP module to the marketplace
- /data-processor-api/unpublish-module - Unpublish Module. Remove an HDP module from the marketplace
- /data-processor-api/get-module-versions - Get Module Versions. Retrieve all versions of a specific HDP module

### Storage Proof API
#### Getting Started
- /storage-proofs-api/introduction - Introduction. Introduction to Storage Proofs
- /storage-proofs-api/use-cases - Use Cases. Storage Proof Use Cases
- /storage-proofs-api/quick-start-guide - Quick Start Guide. Quickly get started with using Storage Proofs
- /storage-proofs-api/key-concepts - Key Concepts. Essential concepts for understanding Storage Proofs including block hashes, inclusion proofs, and zero-knowledge verification
#### AI Skill
- /skills/storage-proof-api - Storage Proof API AI Skill (cross-referenced from Skills)
#### Contracts
- /storage-proofs-api/contracts/accessing-data - Accessing Data On-chain. After API request has finished, access the data on-chain using Satellite contract
- /storage-proofs-api/contracts/example-smart-contract - Example Smart Contract. Example smart contract that uses the Satellite Contract to access Storage Proofs data
- /storage-proofs-api/contracts/contract-addresses - Contract Addresses. Smart contract addresses for verification of Storage Proofs across Ethereum, StarkNet, and other supported chains

### Satellite Contracts
#### Overview
- /satellite-contracts/introduction - Introduction. What Herodotus Satellite Contracts are and why they matter
- /satellite-contracts/for-end-users - For End Users. How to consume proven historical data from Satellite contracts
#### AI Skill
- /skills/satellite-contracts - Satellite Contracts AI Skill (cross-referenced from Skills)
#### Deep Dive
- /satellite-contracts/architecture - Architecture. Satellite design: MMR commitments, proof verification, and contract composition
- /satellite-contracts/module-map - Module Map. Satellite module responsibilities across MMR, proofs, messaging, and operations
- /satellite-contracts/herodotus-stack - How Satellite Powers Herodotus Services. How Satellite connects Storage Proof API, Data Structure Indexer, and HDP
- /satellite-contracts/deployments-and-integration - Deployments and Integration. Where to find deployed satellites, interfaces, and repository resources

### Data Structure Indexer API
#### Data Structure Indexer API
- /data-structure-indexer-api/introduction - Introduction. Overview of the Data Structure Indexer API
#### AI Skill
- /skills/data-structure-indexer-api - Data Structure Indexer API AI Skill (cross-referenced from Skills)

## Machine-readable API specs

- /atlantic-api/openapi-atlantic.json
  - Scope: Atlantic API request/response schemas and endpoint contracts
  - Use when: validating payload shape, query/path parameters, enum values, and error response formats
- /data-processor-api/openapi/openapi-hdp-server.json
  - Scope: HDP Server task/module orchestration API contract
  - Use when: implementing task lifecycle operations, module management, retry/decommitment flows, and status polling
- /storage-proofs-api/openapi-storage-proof-api.json
  - Scope: Storage Proof API contract for proof request lifecycle and related resources
  - Use when: implementing proof requests, checking status transitions, and integrating proof outputs
- /data-structure-indexer-api/openapi-data-structure-indexer-api.json
  - Scope: Data Structure Indexer query contract
  - Use when: retrieving indexer entities and validating query parameters/response objects

When to read OpenAPI vs docs pages:
- Use docs pages first for workflow and conceptual guidance.
- Use OpenAPI files for exact wire contract details (required fields, types, enums, status codes).