Hopsule API Overview: Getting Started with Integrations

Introduction to the Hopsule API

The Hopsule API serves as the programmatic gateway to your organization’s decision-first memory system, allowing engineering teams to integrate authoritative governance and context preservation directly into their custom workflows. By leveraging the Hopsule API, you can ensure that organizational judgment is not confined to a single interface but is instead woven into the very fabric of your development lifecycle, from CI/CD pipelines to custom internal dashboards.

This guide provides a comprehensive overview of how to authenticate, interact with core entities like Decisions and Memories, and utilize Context Packs to maintain a portable and enforceable record of why your team builds the way it does. Understanding these programmatic interfaces is essential for teams looking to scale their decision-making processes without losing the critical reasoning that informs their technical evolution.

Prerequisites for API Integration

Before you begin integrating with the Hopsule API, ensure that you have fulfilled the following requirements to maintain the security and integrity of your organizational memory:

• Active Hopsule Account: You must have a verified account and be a member of an active Organization within the Hopsule Dashboard.

• Organization Permissions: To generate API tokens, you typically need Administrator or Owner-level permissions within your Hopsule Organization.

• Secure Environment: Ensure your integration environment supports TLS 1.3 for secure data transmission, as Hopsule enforces strict encryption standards for all API traffic.

• API Token: A valid Bearer token generated from the Hopsule Dashboard is required for every request.

Authentication and Security

Security is a baseline guarantee at Hopsule. All API requests are protected by end-to-end encryption, utilizing TLS 1.3 for data in transit and AES-256 for data at rest. Authentication is handled via secure API tokens that act as your organization’s digital signature for programmatic actions.

To generate your first API token, follow these steps:

1. Log in to the Hopsule Dashboard and navigate to the Settings menu located in the bottom-left sidebar.

2. Select the API & Integrations tab from the settings navigation.

3. Click the Generate New Token button in the top-right corner of the interface.

4. Provide a descriptive name for the token (e.g., "CI/CD Pipeline Enforcement") and select the appropriate scope for the token's authority.

5. Click Create Token. Copy the generated token immediately; for security reasons, Hopsule does not store the raw token and it will never be displayed again.

All requests to the Hopsule API must include this token in the Authorization header as a Bearer token. For example:

Authorization: Bearer YOUR_API_TOKEN

Authorization: Bearer YOUR_API_TOKEN

Authorization: Bearer YOUR_API_TOKEN

Core Entity: Managing Decisions Programmatically

Decisions are the primary unit of governance within Hopsule. Unlike simple text entries, Decisions are enforceable constraints that guide your team's technical direction. Through the Hopsule API, you can manage the entire lifecycle of a decision: Draft, Pending, Accepted, and Deprecated.

Creating a New Decision

When your team reaches a technical consensus, you can programmatically record this as a Decision. This is particularly useful when integrating with external brainstorming tools or custom project management systems.

1. Send a POST request to the /v1/decisions endpoint.

2. Include a JSON payload containing the title, description, and category.

3. Specify the initial status. It is recommended to start with Draft or Pending to allow for human review within the Hopsule Dashboard.

Once a Decision is created, it is assigned a unique identifier that can be used for future references, linking memories, or enforcement checks in the Hopsule CLI or Hopsule for VS Code.

The Decision Lifecycle and Enforcement

The transition of a Decision to the Accepted state is a significant event in the Hopsule ecosystem. Once a Decision is accepted, it becomes an active constraint. The Hopsule API allows you to trigger these transitions, though we recommend that the final "Acceptance" is always performed by an authorized human member of the team to ensure organizational judgment is upheld.

To update the status of a decision, use the PATCH method on the /v1/decisions/{decision_id} endpoint. When a decision is moved to Deprecated, it remains in the system as a historical record, preserving the memory of why that path was eventually abandoned.

Core Entity: Preserving Memories

Memories are the append-only entries that provide the "why" behind your decisions. In Hopsule, memories are never deleted and never overwritten. They represent the persistent context of your engineering organization. The Hopsule API allows you to append memories to existing decisions or create standalone context entries.

Appending Context to Decisions

As a project evolves, new insights, lessons, or post-mortems should be preserved as memories linked to the original decision. This creates a full traceability map of your team's reasoning.

1. Identify the decision_id you wish to provide context for.

2. Send a POST request to /v1/decisions/{decision_id}/memories.

3. Include the content of the memory and any relevant tags for searchability.

By programmatically appending memories—such as automated performance reports or incident summaries—you ensure that the context surrounding a decision grows over time, preventing organizational amnesia.

Managing Context Packs (Capsules)

Context Packs, or Capsules, are portable bundles of decisions and memories designed to survive time and system changes. They are the primary mechanism for sharing organizational judgment across different projects or AI sessions. The Hopsule API provides full control over the Capsule lifecycle.

Through the API, you can:

• Create Capsules: Bundle a specific set of decisions and memories for a new project kickoff.

• Activate Capsules: Mark a Capsule as Active to make its decisions enforceable in the Hopsule for VS Code extension for a specific repository.

• Freeze Capsules: Transition a Capsule to Frozen when a project is completed, ensuring the context is preserved exactly as it was at the time of delivery.

To list all available Capsules for your organization, use a GET request to the /v1/capsules endpoint. This allows your custom tooling to dynamically select the appropriate context for different environments.

Integrating Hopper via the API

Hopper, the Hopsule AI assistant, is available programmatically to provide advisory insights based on your team's existing memories and decisions. It is important to remember that Hopper is strictly advisory; it can suggest drafts or identify potential contradictions, but it never has the authority to accept a decision autonomously.

You can interact with Hopper via the /v1/hopper/analyze endpoint. By sending a proposed technical change or a new draft decision to this endpoint, Hopper will use RAG-powered (Retrieval-Augmented Generation) analysis to compare the input against your organization's Knowledge Graph. Hopper will then return suggestions or warnings if the proposal contradicts an existing Accepted decision.

Webhooks and Real-Time Enforcement

For organizations that require immediate reaction to decision changes, the Hopsule API supports webhooks. Webhooks allow your external systems to "listen" for specific events within the Hopsule ecosystem.

1. Navigate to the Webhooks section in the Hopsule Dashboard.

2. Click Add Endpoint and enter your listener URL.

3. Select the events you wish to subscribe to, such as decision.accepted, memory.created, or capsule.frozen.

4. Hopsule will send a signed JSON payload to your server whenever these events occur, enabling real-time enforcement in your own infrastructure.

API Rate Limits and Tiers

To ensure the stability and performance of the Hopsule ecosystem, the API is subject to rate limiting based on your organization's plan tier. These limits are designed to accommodate high-velocity engineering teams while preventing abuse.

• Free Tier: Standard rate limits suitable for solo developers and small teams exploring decision governance.

• Pro Tier: Increased limits for active engineering organizations with multiple concurrent integrations.

• Enterprise Tier: Customizable rate limits and higher throughput for large-scale enterprise deployments and self-hosted instances.

When a rate limit is exceeded, the API will return a 429 Too Many Requests status code. Your integration should be designed to handle these responses gracefully using exponential backoff strategies.

Tips and Best Practices

To get the most out of the Hopsule API and maintain a high-quality organizational memory, follow these professional recommendations:

• Link Everything: Whenever you create a memory via the API, link it to a relevant decision. Unlinked memories are harder to discover in the Knowledge Graph.

• Use Descriptive Tags: Programmatically tag decisions and memories with project codes, team names, or technology stacks to improve searchability in the Hopsule Dashboard.

• Automate Enforcement: Use the API in your CI/CD pipelines to check for decision contradictions before code is merged. If a new PR contradicts an Accepted decision, the pipeline should alert the reviewer.

• Respect the Lifecycle: Do not jump straight to the Accepted status for new decisions. Use the Pending state to encourage peer review and collaborative governance.

• Secure Your Tokens: Treat API tokens with the same level of security as your primary credentials. Never hardcode them in source code; use environment variables or secret management systems.

• Monitor Activity: Regularly check the Activity Feed in the Hopsule Dashboard to monitor programmatic changes and ensure your integrations are performing as expected.

Troubleshooting the Hopsule API

If you encounter issues while integrating with the Hopsule API, consult the following table for common causes and solutions.

Related Articles

• Managing API Tokens and Scopes in the Hopsule Dashboard

• Configuring Webhooks for Real-Time Decision Enforcement

• Using the Hopsule CLI for Terminal-Based Governance

• Understanding the Decision Lifecycle: From Draft to Deprecated