Hopsule API: Context Packs (Capsules) Endpoint

Overview of Context Packs (Capsules)

In the Hopsule ecosystem, Context Packs—commonly referred to as Capsules—represent the primary vehicle for portability and context preservation. While individual Decisions and Memories serve as the atoms of your organizational judgment, a Capsule is the molecule that binds them together into a functional, shareable unit. The Hopsule API provides a robust interface for managing these entities programmatically, allowing engineering teams to automate the distribution of context across disparate projects, environments, and AI sessions.

The Capsules endpoint is designed for high-stakes environments where manual management via the Hopsule Dashboard might be insufficient. By utilizing this API, organizations can integrate decision-enforcement into their automated workflows, ensuring that every new repository or project starts with a pre-defined set of architectural constraints and historical reasoning. This programmatic approach supports the Hopsule philosophy: Enforcement is remembrance, not control. By automating the deployment of Capsules, you ensure your team never has to "re-learn" a lesson the hard way.

Important: All interactions with the Hopsule API require a valid Bearer Token, which can be generated within the Hopsule Dashboard under the Organization Settings. Every request is protected by end-to-end encryption, ensuring that your team's most sensitive architectural decisions remain private and secure, even when accessed via automated scripts or CI/CD pipelines.

Authentication and Base URL

All Capsule management requests must be directed to the following base URL. Ensure your client is configured to use TLS 1.3 to maintain the security integrity of your organizational context.

https://api.hopsule.com/v1

https://api.hopsule.com/v1

https://api.hopsule.com/v1

https://api.hopsule.com/v1

Requests must include an Authorization header with your secure token. Failure to provide a token, or providing an expired token, will result in a 401 Unauthorized response. For Hopsule Enterprise users, this base URL may differ depending on your self-hosted configuration; consult your internal infrastructure documentation for the correct endpoint.

List Capsules

The GET /v1/capsules endpoint allows you to retrieve a paginated list of all Context Packs within your organization. This is the primary method for auditing the available context across your various projects and teams. The response includes high-level metadata for each Capsule, including its current lifecycle state (Draft, Active, Frozen, or Historical) and the number of Decisions and Memories it currently encapsulates.

Method: GET
URL: /v1/capsules
Auth: Bearer Token required

Request Parameters

Example Response

{
  "data": [
    {
      "slug": "frontend-architecture-v1",
      "name": "Frontend Architecture Standards",
      "status": "active",
      "decision_count": 12,
      "memory_count": 45,
      "created_at": "2023-10-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "has_more": false
  }
}

{
  "data": [
    {
      "slug": "frontend-architecture-v1",
      "name": "Frontend Architecture Standards",
      "status": "active",
      "decision_count": 12,
      "memory_count": 45,
      "created_at": "2023-10-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "has_more": false
  }
}

{
  "data": [
    {
      "slug": "frontend-architecture-v1",
      "name": "Frontend Architecture Standards",
      "status": "active",
      "decision_count": 12,
      "memory_count": 45,
      "created_at": "2023-10-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "has_more": false
  }
}

{
  "data": [
    {
      "slug": "frontend-architecture-v1",
      "name": "Frontend Architecture Standards",
      "status": "active",
      "decision_count": 12,
      "memory_count": 45,
      "created_at": "2023-10-15T10:00:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "has_more": false
  }
}

Get Capsule with Contents

To retrieve the full details of a specific Context Pack, use the GET /v1/capsules/:slug endpoint. This returns the complete metadata for the Capsule, but does not include the full text of every linked Decision or Memory by default. Instead, it provides a comprehensive overview of the Capsule's purpose, its current status in the Knowledge Graph, and its relationship to other organizational entities.

Method: GET
URL: /v1/capsules/:slug
Auth: Bearer Token required

Tip: Use the slug (a URL-friendly identifier) instead of a numeric ID. Slugs are immutable once a Capsule is Frozen, providing a reliable way to reference context in your scripts and automation tools.

Example Response

{
  "slug": "frontend-architecture-v1",
  "name": "Frontend Architecture Standards",
  "description": "Core constraints for all React-based web applications.",
  "status": "active",
  "owner_id": "user_01H2...",
  "created_at": "2023-10-15T10:00:00Z",
  "updated_at": "2023-11-01T14:30:00Z"
}

{
  "slug": "frontend-architecture-v1",
  "name": "Frontend Architecture Standards",
  "description": "Core constraints for all React-based web applications.",
  "status": "active",
  "owner_id": "user_01H2...",
  "created_at": "2023-10-15T10:00:00Z",
  "updated_at": "2023-11-01T14:30:00Z"
}

{
  "slug": "frontend-architecture-v1",
  "name": "Frontend Architecture Standards",
  "description": "Core constraints for all React-based web applications.",
  "status": "active",
  "owner_id": "user_01H2...",
  "created_at": "2023-10-15T10:00:00Z",
  "updated_at": "2023-11-01T14:30:00Z"
}

{
  "slug": "frontend-architecture-v1",
  "name": "Frontend Architecture Standards",
  "description": "Core constraints for all React-based web applications.",
  "status": "active",
  "owner_id": "user_01H2...",
  "created_at": "2023-10-15T10:00:00Z",
  "updated_at": "2023-11-01T14:30:00Z"
}

Create Capsule

The POST /v1/capsules endpoint is used to initialize a new Context Pack. When a Capsule is first created, it defaults to the Draft state. In this state, you can freely add or remove Decisions and Memories without triggering enforcement warnings in Hopsule for VS Code or Hopsule CLI. This allows teams to curate their context before making it an official part of the organizational governance layer.

Method: POST
URL: /v1/capsules
Auth: Bearer Token required

Request Body Fields

Important: Slugs must be unique within your organization. If you attempt to create a Capsule with a slug that already exists, the Hopsule API will return a 409 Conflict error.

Update Capsule

The PATCH /v1/capsules/:slug endpoint allows you to modify the metadata of an existing Context Pack. This is primarily used for updating descriptions or renaming Capsules that are still in the Draft or Active states. Once a Capsule has been Frozen, most metadata fields become immutable to ensure the integrity of the historical record.

Method: PATCH
URL: /v1/capsules/:slug
Auth: Bearer Token required

Tip: If you need to change the fundamental constraints within a Frozen Capsule, the recommended workflow is to create a new Capsule version and mark the previous one as Historical. This maintains the Knowledge Graph's traceability and ensures that the reasoning behind older decisions is never lost.

Activate Capsule

Moving a Context Pack from Draft to Active is a significant governance event. The POST /v1/capsules/:slug/activate endpoint triggers this transition. Once active, all Accepted Decisions within the Capsule are immediately enforced across all connected surfaces, including Hopsule for VS Code and Hopsule MCP. Developers will begin seeing warnings if their code contradicts the decisions preserved within this Capsule.

Method: POST
URL: /v1/capsules/:slug/activate
Auth: Bearer Token required

Activation also makes the Capsule visible to Hopper, the built-in AI assistant. Hopper will begin using the Memories and Decisions in the Active Capsule as context (via RAG) to provide advisory guidance to the team.

Freeze Capsule

The POST /v1/capsules/:slug/freeze endpoint is used to create an immutable snapshot of a Context Pack. A Frozen Capsule cannot be edited; no new Decisions can be added, and existing ones cannot be modified. This is essential for compliance, auditing, and preserving the state of organizational judgment at a specific point in time (e.g., at the end of a major project phase or a security audit).

Method: POST
URL: /v1/capsules/:slug/freeze
Auth: Bearer Token required

Important: Freezing is an irreversible action. Once a Capsule is Frozen, it serves as a permanent anchor in your organization's Brain. If you need to evolve the decisions contained within, you must branch or create a new Capsule.

Share Capsule

Hopsule is designed for collaboration, and the POST /v1/capsules/:slug/share endpoint facilitates this by generating secure, time-limited tokens for external access. This allows you to share a Context Pack with external consultants, partner organizations, or separate Hopsule instances without granting full access to your Hopsule Dashboard.

Method: POST
URL: /v1/capsules/:slug/share
Auth: Bearer Token required

Request Body

{
  "expires_in_days": 7,
  "access_level": "read-only"
}

{
  "expires_in_days": 7,
  "access_level": "read-only"
}

{
  "expires_in_days": 7,
  "access_level": "read-only"
}

{
  "expires_in_days": 7,
  "access_level": "read-only"
}

The response will include a share_url and a token. These can be used to import the Capsule into another environment or project, ensuring that the necessary context and architectural governance follow the work, regardless of where it is being performed.

Get Capsule Contents

To retrieve the specific Decisions and Memories that constitute a Context Pack, use the GET /v1/capsules/:slug/contents endpoint. This is the most data-intensive endpoint in the Capsules API, as it returns the full text, reasoning, and version history for every linked entity. This endpoint is frequently used by Hopsule MCP to feed context into AI agents.

Method: GET
URL: /v1/capsules/:slug/contents
Auth: Bearer Token required

The contents are returned in a structured format that highlights the relationship between Memories (the "why") and Decisions (the "what"). This traceability is what allows Hopper and other AI tools to explain why a certain constraint exists, rather than just stating that it does.

Best Practices for API Management

When managing Context Packs via the Hopsule API, we recommend adhering to the following organizational practices to ensure long-term context preservation:

• Version Your Capsules: Use semantic versioning in your slugs (e.g., api-design-v1, api-design-v2). This allows you to maintain Historical records while moving the team forward with Active constraints.

• Automate with CI/CD: Use the Hopsule CLI or Hopsule API within your deployment pipelines to verify that the current project state matches the Accepted Decisions in the relevant Capsule.

• Link Memories Liberally: A Capsule is only as strong as the reasoning it contains. Ensure your automated processes append Memories to Decisions whenever a significant change occurs.

• Audit via the Knowledge Graph: Regularly use the Hopsule Dashboard to visualize how your Capsules are interconnected. The Brain view will show you if certain Capsules are becoming isolated or if conflicting Decisions are emerging across different packs.

By treating your Context Packs as first-class citizens in your engineering workflow, you transform "documentation" from a chore into a living, enforceable memory system. The Hopsule API is the key to making this system scale alongside your organization.