Skip to main content

​
Upload Module

Uploads a new HDP module to the registry. This endpoint accepts multipart form data containing the compiled module, source files, ABI, and metadata. The creator user is automatically inferred from the API key. This endpoint requires authentication.

​
Endpoint

POST /modules/upload

​
Authentication

This endpoint requires authentication using an API key: 
X-API-KEY: your-herodotus-cloud-api-key-here

​
Request Body (Multipart Form Data)

FieldTypeRequiredDescription
modulefile (JSON)YesThe compiled contract class JSON file
namestringYesModule name
compiler_versionstringNoCompiler version (extracted from module if not provided)
versionstringYesSemantic version (e.g., “1.0.0”)
descriptionstringNoModule description
tagsstringNoComma-separated tags
licensestringNoLicense identifier
version_changelogstringNoChangelog for this version
source_filesstring (JSON)NoJSON object mapping file paths to content: {"src/lib.cairo": "content", ...}
abistring (JSON)NoModule ABI as JSON
scarb_tomlstringNoScarb.toml file content

​
Example Request

curl -X POST https://staging.hdp.api.herodotus.cloud/modules/upload \
  -H "X-API-KEY: your-herodotus-cloud-api-key-here" \
  -F "module=@my_module.compiled_contract_class.json" \
  -F "name=my_module" \
  -F "version=1.0.0" \
  -F "description=My awesome HDP module" \
  -F "tags=example,tutorial" \
  -F "license=MIT" \
  -F "version_changelog=Initial release" \
  -F "source_files={\"src/lib.cairo\": \"fn main() {}\"}" \
  -F "abi={\"type\": \"interface\", ...}" \
  -F "scarb_toml=[package]\nname = \"my_module\"\n..."

​
Response

​
Success Response (201 Created)

{
  "id": "01JPJ03YJT1A93D6NF56G4GVEQ",
  "programHash": "0x34a16478e83f69c4f0bcdb7549d32f92c9b7776bb3f71da06de334f1871eba0",
  "compilerVersion": "2.7.0",
  "createdAt": "2024-03-17T10:24:00Z",
  "message": "Module uploaded successfully"
}

​
Error Response (400 Bad Request)

{
  "error": "Version 1.0.0 already exists for this module"
}

​
Error Response (401 Unauthorized)

{
  "error": "Missing Herodotus Cloud X-API-KEY header"
}

​
Response Fields

FieldTypeDescription
idstringThe unique module ID (ULID)
programHashstringThe program hash of the uploaded module
compilerVersionstringThe compiler version used
createdAtstringISO 8601 timestamp of module creation
messagestringSuccess message

​
Version Management

  • Each module can have multiple versions
  • Version numbers must be unique per module (semantic versioning recommended)
  • The uploaded version becomes the latest version for the module
  • If a version already exists for the module, the upload will fail with a 400 error

​
Storage

  • Compiled programs are stored in S3 (if configured) or in the database as fallback
  • Source code is always stored in the database
  • Scarb.toml is stored in the database for reference

​
Notes

  • Authentication is required for this endpoint
  • The creator user is automatically inferred from the API key
  • The module must be a Cairo 1 compiled program (Cairo 0 is not supported)
  • The compiler version is extracted from the module if not provided
  • Source files should be provided as a JSON object mapping relative paths to file contents
  • The ABI should be provided as a JSON string
  • Duplicate versions for the same module are not allowed