Skip to main content
Version: Next

Admin API Reference

The Calimero Admin API provides programmatic access to manage various aspects of a Calimero node. This API is essential for building administrative tools, monitoring systems, and integrating Calimero nodes into existing infrastructure.

Base URL​

All admin API endpoints are served under the /admin-api path:

http://your-node-address:port/admin-api

Authentication​

The admin API supports session-based authentication. When enabled, endpoints require valid authentication credentials.

Response Format​

All API responses follow a consistent JSON format:

{
  "payload": {
    // Response data here
  }
}

Error responses include an error message:

{
  "error": "Error description"
}

Endpoints​

Health Check​

GET /admin-api/health​

Check if the admin API is running and healthy.

Response:

{
  "payload": {
    "data": {
      "status": "alive"
    }
  }
}

Authentication Status​

GET /admin-api/is-authed​

Check if the current request is authenticated.

Response:

{
  "payload": {
    "data": {
      "is_authed": true
    }
  }
}

SSL Certificate​

GET /admin-api/certificate​

Retrieve the SSL certificate for the node.

Response:

{
  "payload": {
    "data": {
      "certificate": "-----BEGIN CERTIFICATE-----\n..."
    }
  }
}

Application Management​

note

The admin API endpoints for application management provide the same functionality as the meroctl CLI tool. Both support installing applications from local file paths and remote URLs.

Install Application​

POST /admin-api/install-application​

Install a new application on the node. This endpoint requires a publicly accessible HTTP/HTTPS URL for the WASM file.

Request Body:

Example with descriptive placeholders:

{
  "url": "https://example.com/application.wasm",
  "metadata": [],
  "hash": "optional-hash-value"
}

Example with realistic dummy values:

{
  "url": "https://github.com/calimero/example-app/releases/v1.0.0/app.wasm",
  "metadata": [],
  "hash": "8BtADbnT4DyX6P7rYjKh2trR5zk3nk5L5zSp4G7rHArc"
}

Required Fields:

  • url: HTTP/HTTPS URL to the WASM file (local file paths are not supported)
  • metadata: Array of bytes (can be empty [] for basic installation)

Optional Fields:

  • hash: Optional hash verification for the WASM file

Response:

{
  "data": {
    "applicationId": "HiHvjUJwQEAJKYr9yaTUPcNQi8BfBdnBWEVGqVFNHFF"
  }
}
note

Important: The url field must be a valid HTTP/HTTPS URL. Local file paths (/path/to/file.wasm) and file protocol URLs (file:///path/to/file.wasm) are not supported for security reasons.

Testing with Local Files: To test with local WASM files, you need to serve them via a local HTTP server first:

# Start a local HTTP server in the directory containing your WASM file
cd /path/to/your/wasm/files
python3 -m http.server 8000

# Then use the HTTP URL in your request
curl -X POST http://localhost:2428/admin-api/install-application \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://localhost:8000/your-app.wasm",
    "metadata": []
  }'

Install Development Application​

POST /admin-api/install-dev-application​

Install a development version of an application. This endpoint supports both local file paths and remote URLs.

Request Body:

Example with descriptive placeholders:

{
  "path": "/path/to/dev-application.wasm",
  "metadata": []
}

Example with realistic dummy values:

{
  "path": "/Users/developer/projects/my-app/target/wasm32-unknown-unknown/release/app.wasm",
  "metadata": []
}

Alternative Request Body (URL-based):

Example with descriptive placeholders:

{
  "path": "https://example.com/dev-application.wasm",
  "metadata": []
}

Example with realistic dummy values:

{
  "path": "https://github.com/calimero/example-app/releases/nightly/app.wasm",
  "metadata": []
}
note

Similar to the main install endpoint, the path field accepts both local file paths and remote URLs for development applications.

Working Examples​

Example 1: Install Application from Local HTTP Server​

# Step 1: Start a local HTTP server
cd /path/to/your/wasm/files
python3 -m http.server 8000

# Step 2: Install the application
curl -X POST http://localhost:2428/admin-api/install-application \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://localhost:8000/your-app.wasm",
    "metadata": []
  }'

Expected Response:

{
  "data": {
    "applicationId": "HiHvjUJwQEAJKYr9yaTUPcNQi8BfBdnBWEVGqVFNHFF"
  }
}

Example 2: Install Application from Remote URL​

curl -X POST http://localhost:2428/admin-api/install-application \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/application.wasm",
    "metadata": []
  }'

Example 3: Install with Metadata (Advanced)​

# If you need to include metadata, encode it as bytes
curl -X POST http://localhost:2428/admin-api/install-application \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://localhost:8000/your-app.wasm",
    "metadata": [99, 117, 114, 98],
    "hash": "optional-hash-here"
  }'

Understanding Metadata​

The metadata field allows you to attach additional information to your application installation. While optional, it's useful for tracking application details and displaying information in the admin dashboard.

Metadata Structure​

The admin dashboard uses this metadata structure:

interface AppMetadata {
  applicationUrl: string; // URL where the WASM file is hosted
  applicationName: string; // Human-readable name of the application
  applicationOwner: string; // Name of the developer/owner
  applicationVersion: string; // Version number (e.g., "1.0.0")
  description: string; // Brief description of the application
  contractAppId: string; // Optional contract identifier
  repositoryUrl: string; // Link to source code repository
}

How Metadata Gets Encoded​

The metadata must be provided as an array of bytes (0-255 values). The admin dashboard automatically handles this encoding:

function createAppMetadata(application: AppMetadata): Uint8Array {
  return new TextEncoder().encode(JSON.stringify(application));
}

Metadata Examples​

Example 1: Empty Metadata (Simplest)

{
  "url": "http://localhost:8000/app.wasm",
  "metadata": []
}

Example 2: Basic Metadata (Name and Version)

{
  "url": "http://localhost:8000/app.wasm",
  "metadata": [
    123, 34, 110, 97, 109, 101, 34, 58, 34, 67, 117, 114, 98, 32, 65, 112, 112,
    34, 44, 34, 118, 101, 114, 115, 105, 111, 110, 34, 58, 34, 49, 46, 48, 46,
    48, 34, 125
  ]
}

This represents: {"name":"Curb App","version":"1.0.0"}

Example 3: Full Metadata Structure

{
  "url": "http://localhost:8000/app.wasm",
  "metadata": [
    123, 34, 97, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 78, 97, 109,
    101, 34, 58, 34, 67, 117, 114, 98, 32, 67, 104, 97, 116, 34, 44, 34, 97,
    112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 79, 119, 110, 101, 114, 34,
    58, 34, 65, 110, 116, 111, 110, 34, 44, 34, 97, 112, 112, 108, 105, 99, 97,
    116, 105, 111, 110, 86, 101, 114, 115, 105, 111, 110, 34, 58, 34, 49, 46,
    48, 46, 48, 34, 44, 34, 100, 101, 115, 99, 114, 105, 112, 116, 105, 111,
    110, 34, 58, 34, 76, 111, 99, 97, 108, 32, 116, 101, 115, 116, 32, 105, 110,
    115, 116, 97, 108, 108, 97, 116, 105, 111, 110, 34, 125
  ]
}

This represents: {"applicationName":"Curb Chat","applicationOwner":"Anton","applicationVersion":"1.0.0","description":"Local test installation"}

How to Generate Metadata Bytes​

Option 1: Use JavaScript/Node.js

const metadata = {
  applicationName: 'My App',
  applicationVersion: '1.0.0',
};

const bytes = Array.from(new TextEncoder().encode(JSON.stringify(metadata)));
console.log(bytes); // [123, 34, 97, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 78, 97, 109, 101, 34, 58, 34, 77, 121, 32, 65, 112, 112, 34, 44, 34, 97, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 86, 101, 114, 115, 105, 111, 110, 34, 58, 34, 49, 46, 48, 46, 48, 34, 125]

Option 2: Use Online Tools

  • Convert your JSON to bytes using online text-to-bytes converters
  • Or use the admin dashboard which handles encoding automatically

When to Use Metadata​

  • Empty []: For quick testing and basic installations
  • Basic metadata: When you want to track app name and version
  • Full metadata: For production deployments where you need complete app information

Metadata Best Practices​

  1. Keep it simple: Start with empty metadata for testing
  2. Use consistent naming: Follow the same structure across applications
  3. Include essential info: At minimum, include applicationName and applicationVersion
  4. Avoid sensitive data: Don't include API keys, passwords, or private information

List Applications​

GET /admin-api/applications​

Get a list of all installed applications.

Troubleshooting Common Issues​

Issue: "Failed to deserialize the JSON body into the target type: missing field url"​

Cause: Using path instead of url field Solution: Use url field for the install endpoint:

{
  "url": "http://example.com/app.wasm",
  "metadata": []
}

Issue: "Failed to deserialize the JSON body into the target type: metadata: invalid type: map, expected a sequence"​

Cause: Metadata should be an array, not an object Solution: Use array format:

{
  "url": "http://example.com/app.wasm",
  "metadata": []
}

Issue: "Failed to deserialize the JSON body into the target type: metadata[0]: invalid type: string, expected u8"​

Cause: Metadata array should contain numbers (0-255), not strings Solution: Use empty array or encode strings as byte values:

{
  "url": "http://example.com/app.wasm",
  "metadata": []
}

Issue: "HTTP 404 Not Found" on /admin-api/install-dev-application​

Cause: The dev endpoint may not be available on your node version Solution: Use the regular install endpoint with an HTTP URL instead

Issue: "relative URL without a base" or "file:// protocol not supported"​

Cause: Local file paths and file:// URLs are not supported Solution: Serve your WASM file via HTTP server:

# Start local HTTP server
cd /path/to/wasm/files
python3 -m http.server 8000

# Use HTTP URL
curl -X POST http://localhost:2428/admin-api/install-application \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://localhost:8000/app.wasm",
    "metadata": []
  }'

Issue: "error sending request for url" or "builder error for url"​

Cause: The URL is not accessible or the web server is not running Solution:

  1. Verify the web server is running
  2. Test URL accessibility: curl http://localhost:8000/app.wasm
  3. Check firewall/network settings

Issue: App installed but not visible in admin dashboard​

Cause: Dashboard may be pointing to different node or have connection issues Solution:

  1. Verify app exists via CLI: meroctl --node node1 app list
  2. Check dashboard node configuration
  3. Verify dashboard can access the admin API

Response:

{
  "payload": {
    "data": [
      {
        "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "name": "My Application",
        "version": "1.0.0",
        "installed_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Application​

GET /admin-api/applications/:application_id​

Get details of a specific application.

Response:

{
  "payload": {
    "data": {
      "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "name": "My Application",
      "version": "1.0.0",
      "installed_at": "2024-01-01T00:00:00Z",
      "contexts_count": 5
    }
  }
}

Uninstall Application​

DELETE /admin-api/applications/:application_id​

Remove an application from the node.

Response:

{
  "payload": {
    "data": {
      "success": true,
      "message": "Application uninstalled successfully"
    }
  }
}

Context Management​

Create Context​

POST /admin-api/contexts​

Create a new context.

Request Body:

Example with descriptive placeholders:

{
  "application_id": "application_identity_hash",
  "name": "context_name",
  "protocol": "near"
}

Example with realistic dummy values:

{
  "application_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
  "name": "My Context",
  "protocol": "near"
}

Response:

{
  "payload": {
    "data": {
      "context_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "name": "My Context",
      "application_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "created_at": "2024-01-01T00:00:00Z"
    }
  }
}

List Contexts​

GET /admin-api/contexts​

Get a list of all contexts.

Response:

{
  "payload": {
    "data": [
      {
        "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "name": "My Context",
        "application_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "created_at": "2024-01-01T00:00:00Z",
        "members_count": 3
      }
    ]
  }
}

Get Context​

GET /admin-api/contexts/:context_id​

Get details of a specific context.

Response:

{
  "payload": {
    "data": {
      "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "name": "My Context",
      "application_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "created_at": "2024-01-01T00:00:00Z",
      "members": [
        {
          "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
          "alias": "alice",
          "capabilities": ["read", "write"]
        }
      ]
    }
  }
}

Delete Context​

DELETE /admin-api/contexts/:context_id​

Delete a context and all its data.

Response:

{
  "payload": {
    "data": {
      "success": true,
      "message": "Context deleted successfully"
    }
  }
}

Invite to Context​

POST /admin-api/contexts/invite​

Invite a peer to join a context.

Request Body:

Example with descriptive placeholders:

{
  "context_id": "context_identity_hash",
  "invitee_identity": "invitee_public_key",
  "inviter_identity": "inviter_identity_hash"
}

Example with realistic dummy values:

{
  "context_id": "A4NyeJydZYKeSDiDV4CHYADVGywVekWEubi47Syf6FQy",
  "invitee_identity": "57kiq6jgag3iL7vp4D5iwFLnecB4sig9sP6ELJLv87tL",
  "inviter_identity": "3aipBNQaNzkWeMrSTzWwAQRdfWvwvFXqSKCZ1CBT8d4k"
}

Note: This endpoint corresponds to the CLI command meroctl context invite {invitee_identity} --as {inviter_identity} -c {context_id}. The invitee_identity is the public key of the person being invited, inviter_identity is the identity of the person doing the inviting, and context_id specifies which context to invite them to.

Join Context​

POST /admin-api/contexts/join​

Accept an invitation to join a context.

Request Body:

Example with descriptive placeholders:

{
  "invitation_payload": "base64_encoded_invitation_payload"
}

Example with realistic dummy values:

{
  "invitation_payload": "maWT6kDxpR1EMXb2YSXzdHkegU76QVcf3yXUAyDUEQ27nuHJkpYQbyota6BpZbaouxDn1biAywcj2GnUSRurDn2mvjMwuo6WrjvvgvvAUGDKmAtzN7oqhtWVt5cGEucgrZaei7S255e1KXikmFHWN8UPKMBkuWVFq"
}

Note: This endpoint corresponds to the CLI command meroctl context join {invitation_payload}. The invitation_payload is the result of a successful context invite operation and contains all the necessary information to join the context, including the context ID and invitation details.

Update Context Application​

POST /admin-api/contexts/:context_id/application​

Update the application associated with a context.

Request Body:

{
  "application_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
}

Get Context Storage​

GET /admin-api/contexts/:context_id/storage​

Get the raw storage data for a context.

Response:

{
  "payload": {
    "data": {
      "entries": [
        {
          "key": "user:alice",
          "value": "encrypted_data_here"
        }
      ],
      "total_size": 1024
    }
  }
}

Get Context Identities​

GET /admin-api/contexts/:context_id/identities​

Get all identities in a context.

Response:

{
  "payload": {
    "data": [
      {
        "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "alias": "alice",
        "capabilities": ["read", "write"],
        "joined_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Owned Context Identities​

GET /admin-api/contexts/:context_id/identities-owned​

Get only the identities owned by the current user in a context.

Response:

{
  "payload": {
    "data": [
      {
        "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "alias": "alice",
        "capabilities": ["read", "write"],
        "joined_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Grant Capabilities​

POST /admin-api/contexts/:context_id/capabilities/grant​

Grant capabilities to an identity in a context.

Request Body:

{
  "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
  "capabilities": ["read", "write", "admin"]
}

Revoke Capabilities​

POST /admin-api/contexts/:context_id/capabilities/revoke​

Revoke capabilities from an identity in a context.

Request Body:

{
  "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
  "capabilities": ["admin"]
}

Identity Management​

Generate Context Identity​

POST /admin-api/identity/context​

Generate a new identity for use in a context.

Request Body:

{
  "context_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
}

Response:

{
  "payload": {
    "data": {
      "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "private_key": "base64_encoded_private_key"
    }
  }
}

Proposal Management​

Get Active Proposals Count​

GET /admin-api/contexts/:context_id/proposals/count​

Get the number of active proposals in a context.

Response:

{
  "payload": {
    "data": {
      "count": 5
    }
  }
}

Get Proposals​

POST /admin-api/contexts/:context_id/proposals​

Get a list of proposals in a context.

Request Body:

{
  "limit": 10,
  "offset": 0,
  "status": "active"
}

Response:

{
  "payload": {
    "data": [
      {
        "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "title": "Update Protocol",
        "status": "active",
        "created_by": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Proposal​

GET /admin-api/contexts/:context_id/proposals/:proposal_id​

Get details of a specific proposal.

Response:

{
  "payload": {
    "data": {
      "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "title": "Update Protocol",
      "description": "Update to latest protocol version",
      "status": "active",
      "created_by": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "created_at": "2024-01-01T00:00:00Z",
      "approvals_count": 3,
      "required_approvals": 5
    }
  }
}

Get Proposal Approvals Count​

GET /admin-api/contexts/:context_id/proposals/:proposal_id/approvals/count​

Get the number of approvals for a proposal.

Response:

{
  "payload": {
    "data": {
      "count": 3,
      "required": 5
    }
  }
}

Get Proposal Approvers​

GET /admin-api/contexts/:context_id/proposals/:proposal_id/approvals/users​

Get the list of users who approved a proposal.

Response:

{
  "payload": {
    "data": [
      {
        "identity": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "alias": "alice",
        "approved_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Get Context Value​

POST /admin-api/contexts/:context_id/proposals/get-context-value​

Get a specific value from the context storage.

Request Body:

{
  "key": "user:alice"
}

Get Context Storage Entries​

POST /admin-api/contexts/:context_id/proposals/context-storage-entries​

Get multiple storage entries from a context.

Request Body:

{
  "keys": ["user:alice", "user:bob"],
  "limit": 100
}

Get Proxy Contract​

GET /admin-api/contexts/:context_id/proxy-contract​

Get the proxy contract information for a context.

Response:

{
  "payload": {
    "data": {
      "contract_address": "0x1234...",
      "network": "ethereum",
      "status": "active"
    }
  }
}

Context Synchronization​

Sync Context​

POST /admin-api/contexts/sync​

Synchronize a context with the network.

Request Body:

{
  "context_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
}

POST /admin-api/contexts/sync/:context_id​

Synchronize a specific context.

Network Information​

Get Peers Count​

GET /admin-api/peers​

Get the number of connected peers.

Response:

{
  "payload": {
    "data": {
      "count": 15,
      "active": 12
    }
  }
}

Blob Management​

Upload Blob​

PUT /admin-api/blobs​

Upload a new blob to the node.

Request Body: Binary data

Headers:

Content-Type: application/octet-stream

Response:

{
  "payload": {
    "data": {
      "blob_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "size": 1024,
      "uploaded_at": "2024-01-01T00:00:00Z"
    }
  }
}

List Blobs​

GET /admin-api/blobs​

Get a list of all blobs.

Response:

{
  "payload": {
    "data": [
      {
        "id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
        "size": 1024,
        "uploaded_at": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Download Blob​

GET /admin-api/blobs/:blob_id​

Download a blob by ID.

Response: Binary data

Headers:

Content-Type: application/octet-stream
Content-Disposition: attachment; filename="blob.bin"

Get Blob Info​

HEAD /admin-api/blobs/:blob_id​

Get metadata about a blob without downloading it.

Response Headers:

Content-Length: 1024
Content-Type: application/octet-stream
X-Uploaded-At: 2024-01-01T00:00:00Z

Delete Blob​

DELETE /admin-api/blobs/:blob_id​

Delete a blob from the node.

Response:

{
  "payload": {
    "data": {
      "success": true,
      "message": "Blob deleted successfully"
    }
  }
}

Alias Management​

Create Alias​

POST /admin-api/alias/create/context​

Create an alias for a context.

Request Body:

{
  "name": "my-context",
  "target": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
}

POST /admin-api/alias/create/application​

Create an alias for an application.

Request Body:

{
  "name": "my-app",
  "target": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
}

POST /admin-api/alias/create/identity/:context​

Create an alias for an identity in a context.

Request Body:

{
  "name": "alice",
  "target": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
}

Lookup Alias​

POST /admin-api/alias/lookup/context/:name​

Look up a context by alias.

Response:

{
  "payload": {
    "data": {
      "target": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
      "created_at": "2024-01-01T00:00:00Z"
    }
  }
}

POST /admin-api/alias/lookup/application/:name​

Look up an application by alias.

POST /admin-api/alias/lookup/identity/:context/:name​

Look up an identity by alias in a specific context.

Delete Alias​

POST /admin-api/alias/delete/context/:name​

Delete a context alias.

POST /admin-api/alias/delete/application/:name​

Delete an application alias.

POST /admin-api/alias/delete/identity/:context/:name​

Delete an identity alias.

List Aliases​

GET /admin-api/alias/list/context​

List all context aliases.

GET /admin-api/alias/list/application​

List all application aliases.

GET /admin-api/alias/list/identity/:context​

List all identity aliases in a context.

Error Handling​

The admin API returns appropriate HTTP status codes and error messages:

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 500 Internal Server Error: Server-side error

Rate Limiting​

The admin API may implement rate limiting to prevent abuse. Check response headers for rate limit information.

WebSocket Support​

Some endpoints support WebSocket connections for real-time updates. Check the specific endpoint documentation for WebSocket support details.

Examples​

Complete Workflow: Create Context and Invite Users​

# 1. Create a context
curl -X POST http://localhost:2428/admin-api/contexts \
  -H "Content-Type: application/json" \
  -d '{
    "application_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf",
    "name": "Team Collaboration",
    "protocol": "near"
  }'

# 2. Generate an identity for the context
curl -X POST http://localhost:2428/admin-api/identity/context \
  -H "Content-Type: application/json" \
  -d '{
    "context_id": "3Hfk2VekXQ58vYHW3hUtA3mh2Rwtb1brV1RKEXtfvfsf"
  }'

# 3. Invite a peer to the context
curl -X POST http://localhost:2428/admin-api/contexts/invite \
  -H "Content-Type: application/json" \
  -d '{
    "context_id": "A4NyeJydZYKeSDiDV4CHYADVGywVekWEubi47Syf6FQy",
    "invitee_identity": "57kiq6jgag3iL7vp4D5iwFLnecB4sig9sP6ELJLv87tL",
    "inviter_identity": "3aipBNQaNzkWeMrSTzWwAQRdfWvwvFXqSKCZ1CBT8d4k"
  }'

# 4. Accept the invitation (using the payload from step 3)
curl -X POST http://localhost:2428/admin-api/contexts/join \
  -H "Content-Type: application/json" \
  -d '{
    "invitation_payload": "maWT6kDxpR1EMXb2YSXzdHkegU76QVcf3yXUAyDUEQ27nuHJkpYQbyota6BpZbaouxDn1biAywcj2GnUSRurDn2mvjMwuo6WrjvvgvvAUGDKmAtzN7oqhtWVt5cGEucgrZaei7S255e1KXikmFHWN8UPKMBkuWVFq"
  }'

Monitoring Node Health​

# Check API health
curl http://localhost:2428/admin-api/health

# Get peer count
curl http://localhost:2428/admin-api/peers

# List all contexts
curl http://localhost:2428/admin-api/contexts

Understanding Metadata​

The metadata field allows you to attach additional information to your application installation. While optional, it's useful for tracking application details and displaying information in the admin dashboard.

Metadata Structure​

The admin dashboard uses this metadata structure:

interface AppMetadata {
  applicationUrl: string; // URL where the WASM file is hosted
  applicationName: string; // Human-readable name of the application
  applicationOwner: string; // Name of the developer/owner
  applicationVersion: string; // Version number (e.g., "1.0.0")
  description: string; // Brief description of the application
  contractAppId: string; // Optional contract identifier
  repositoryUrl: string; // Link to source code repository
}

How Metadata Gets Encoded​

The metadata must be provided as an array of bytes (0-255 values). The admin dashboard automatically handles this encoding:

function createAppMetadata(application: AppMetadata): Uint8Array {
  return new TextEncoder().encode(JSON.stringify(application));
}

Metadata Examples​

Example 1: Empty Metadata (Simplest)

{
  "url": "http://localhost:8000/app.wasm",
  "metadata": []
}

Example 2: Basic Metadata (Name and Version)

{
  "url": "http://localhost:8000/app.wasm",
  "metadata": [
    123, 34, 110, 97, 109, 101, 34, 58, 34, 67, 117, 114, 98, 32, 65, 112, 112,
    34, 44, 34, 118, 101, 114, 115, 105, 111, 110, 34, 58, 34, 49, 46, 48, 46,
    48, 34, 125
  ]
}

This represents: {"name":"Curb App","version":"1.0.0"}

Example 3: Full Metadata Structure

{
  "url": "http://localhost:8000/app.wasm",
  "metadata": [
    123, 34, 97, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 78, 97, 109,
    101, 34, 58, 34, 67, 117, 114, 98, 32, 67, 104, 97, 116, 34, 44, 34, 97,
    112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 79, 119, 110, 101, 114, 34,
    58, 34, 65, 110, 116, 111, 110, 34, 44, 34, 97, 112, 112, 108, 105, 99, 97,
    116, 105, 111, 110, 86, 101, 114, 115, 105, 111, 110, 34, 58, 34, 49, 46,
    48, 46, 48, 34, 44, 34, 100, 101, 115, 99, 114, 105, 112, 116, 105, 111,
    110, 34, 58, 34, 76, 111, 99, 97, 108, 32, 116, 101, 115, 116, 32, 105, 110,
    115, 116, 97, 108, 108, 97, 116, 105, 111, 110, 34, 125
  ]
}

This represents: {"applicationName":"Curb Chat","applicationOwner":"Anton","applicationVersion":"1.0.0","description":"Local test installation"}

How to Generate Metadata Bytes​

Option 1: Use JavaScript/Node.js

const metadata = {
  applicationName: 'My App',
  applicationVersion: '1.0.0',
};

const bytes = Array.from(new TextEncoder().encode(JSON.stringify(metadata)));
console.log(bytes); // [123, 34, 97, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 78, 97, 109, 101, 34, 58, 34, 77, 121, 32, 65, 112, 112, 34, 44, 34, 97, 112, 112, 108, 105, 99, 97, 116, 105, 111, 110, 86, 101, 114, 115, 105, 111, 110, 34, 58, 34, 49, 46, 48, 46, 48, 34, 125]

Option 2: Use Online Tools

  • Convert your JSON to bytes using online text-to-bytes converters
  • Or use the admin dashboard which handles encoding automatically

When to Use Metadata​

  • Empty []: For quick testing and basic installations
  • Basic metadata: When you want to track app name and version
  • Full metadata: For production deployments where you need complete app information

Metadata Best Practices​

  1. Keep it simple: Start with empty metadata for testing
  2. Use consistent naming: Follow the same structure across applications
  3. Include essential info: At minimum, include applicationName and applicationVersion
  4. Avoid sensitive data: Don't include API keys, passwords, or private information

Troubleshooting Common Issues​

Next Steps​

  • Build Admin Tools: Use these endpoints to create custom administrative interfaces
  • Monitor Nodes: Implement monitoring and alerting based on API responses
  • Automate Operations: Create scripts for common administrative tasks
  • Integration: Connect Calimero nodes to existing infrastructure management systems
Was this page helpful?
Need some help? Check Support page