Reference

Authentication

All requests to the Hyperterminal API require authentication via an API key.

Keys use the prefix ht_live_ followed by 48 hex characters:

ht_live_a1b2c3d4e5f6...

Security Best Practices:

• Keys are hashed with SHA-256 before storage. Plaintext keys are never stored on our end.
• All traffic must use HTTPS.
• Your key is shown once at creation time. Store it somewhere safe.

Rate Limits

Free Tier

This allowance is generally enough for standard MCP usage and personal dashboards.

Every API response includes headers showing your current usage so your client can gracefully handle backoffs:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1709078400

Note: Exceeding the per-minute limit returns 429 Too Many Requests. Exceeding your monthly quota returns 401 Unauthorized.

Edge Rate Limits

To protect against unauthenticated abuse, an additional IP-based rate limit runs at the edge (before authentication). This runs independently of your API key limits:

Transports

The MCP server supports two transport protocols. Both expose the same 6 tools and 2 resources.

stdio (default)

The client spawns the server as a local child process. Communication happens over stdin/stdout. This is the standard setup for IDE integrations like Claude Code, Claude Desktop, and Cursor.

npx -y @hyperterminal-ai/mcp-server

Streamable HTTP (hosted)

A hosted Streamable HTTP endpoint is available at https://hyperterminal.ai/api/mcp. Authenticate with your API key as a Bearer token in the Authorization header. No server to run yourself.

POST https://hyperterminal.ai/api/mcp
Authorization: Bearer ht_live_your_key

The endpoint is stateless — each request is independent, no session management required. Send standard MCP JSON-RPC messages (initialize, tools/list, tools/call, etc.) as the request body.

See the Quickstart for client configuration examples.

API Conventions

Success Envelope

All successful responses across the API follow a standardized envelope shape containing ok, data, and optionally meta for pagination:

Highlighted lines below are the contract fields your client should always check first.

{
  "ok": true, 
  "data": { }, 
  "meta": {
    "timestamp": "2026-02-27T12:00:00Z",
    "page": 1,
    "limit": 10,
    "total": 142,
    "has_more": true
  }
}

Date Formats

The API strictly enforces standard date formats for inputs and outputs:

Errors & Troubleshooting

All errors follow a consistent, predictable format so your agent or application can parse them easily:

Highlighted lines below are the minimum fields to branch error handling logic.

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE", 
    "message": "Human-readable description"
  }
}

Error Codes

Common Validation Issues

If you are receiving VALIDATION_ERROR codes, double-check these common pitfalls:

• from and to must be ISO 8601 UTC datetime strings (e.g., 2026-02-01T00:00:00Z). Timezone offsets like +05:00 will be rejected.
• The from date must be strictly earlier than to when both are provided.
• Week keys must exactly match the YYYY-WNN format (e.g., 2026-W09).