Hopsule API: Decisions Endpoint

Overview of the Decisions API

The Decisions API is the programmatic gateway to Hopsule’s core governance layer. Decisions in Hopsule are not merely static documentation entries; they are first-class, enforceable entities that represent the explicit commitments and organizational judgment of an engineering team. By utilizing this API, organizations can integrate Hopsule’s decision-making lifecycle directly into their existing workflows, custom dashboards, and automated governance pipelines.

Every decision managed through this API follows a strict lifecycle designed to ensure that no commitment is made in a vacuum. From the initial Draft phase to the Accepted state—where a decision becomes an enforceable constraint within Hopsule for VS Code—the API provides the necessary endpoints to manage state transitions, preserve context, and maintain a complete audit trail of why specific paths were chosen. This ensures that as teams scale and people change, the reasoning behind every architectural choice remains preserved and accessible.

Important: All write operations to the Decisions API require appropriate permissions. While Hopper can assist in drafting decisions via natural language, the API ensures that only authorized human team members can move a decision to the Accepted state, maintaining the principle that AI is advisory while humans retain ultimate authority.

Authentication and Authorization

To interact with the Hopsule API, all requests must include a valid Bearer token in the Authorization header. These tokens are managed within the Hopsule Dashboard under the organization settings. Hopsule employs end-to-end encryption for all data, and your API keys are the primary mechanism for accessing your encrypted decision layer. Ensure that these tokens are stored securely and never exposed in client-side code.

Authorization: Bearer YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

The API utilizes role-based access control (RBAC). Certain endpoints, such as accepting or deprecating a decision, require administrative or lead-level permissions. If a request is made with a token that lacks sufficient privileges, the API will return a 403 Forbidden response. This ensures that the integrity of your team's governance remains intact even when using programmatic integrations.

The Decision Lifecycle

Understanding the state machine of a decision is critical for effective API integration. A decision moves through the following states:

• Draft: The initial state. Decisions are being formulated and are only visible to the author and designated collaborators. They do not yet influence the Knowledge Graph or IDE enforcement.

• Pending: The decision has been submitted for review. It is visible to the entire team, but its constraints are not yet active. This is the stage for peer review and conflict detection.

• Accepted: The decision is now an active commitment. It is synchronized with Hopsule for VS Code and Hopsule MCP, providing real-time enforcement and context to developers and AI agents alike.

• Deprecated: The decision is no longer active but is preserved for historical context. It remains in the Brain to explain why a previous path was abandoned, ensuring the organization never repeats past mistakes.

List Decisions

GET /v1/decisions

This endpoint retrieves a paginated list of decisions within the authenticated organization. It is highly configurable, allowing you to filter by state, tags, or specific authors. This is the primary method for populating custom internal dashboards or generating governance reports.

Query Parameters

Example Request

GET /v1/decisions?state=accepted&tag=security&limit=10

GET /v1/decisions?state=accepted&tag=security&limit=10

GET /v1/decisions?state=accepted&tag=security&limit=10

GET /v1/decisions?state=accepted&tag=security&limit=10

Example Response

{
  "data": [
    {
      "id": "dec_12345",
      "slug": "standardize-on-aes-256",
      "title": "Standardize on AES-256 for Data at Rest",
      "state": "accepted",
      "author": "user_987",
      "created_at": "2023-10-27T10:00:00Z",
      "tags": ["security", "encryption"]
    }
  ],
  "pagination": {
    "total": 145,
    "page": 1,
    "limit": 10
  }
}

{
  "data": [
    {
      "id": "dec_12345",
      "slug": "standardize-on-aes-256",
      "title": "Standardize on AES-256 for Data at Rest",
      "state": "accepted",
      "author": "user_987",
      "created_at": "2023-10-27T10:00:00Z",
      "tags": ["security", "encryption"]
    }
  ],
  "pagination": {
    "total": 145,
    "page": 1,
    "limit": 10
  }
}

{
  "data": [
    {
      "id": "dec_12345",
      "slug": "standardize-on-aes-256",
      "title": "Standardize on AES-256 for Data at Rest",
      "state": "accepted",
      "author": "user_987",
      "created_at": "2023-10-27T10:00:00Z",
      "tags": ["security", "encryption"]
    }
  ],
  "pagination": {
    "total": 145,
    "page": 1,
    "limit": 10
  }
}

{
  "data": [
    {
      "id": "dec_12345",
      "slug": "standardize-on-aes-256",
      "title": "Standardize on AES-256 for Data at Rest",
      "state": "accepted",
      "author": "user_987",
      "created_at": "2023-10-27T10:00:00Z",
      "tags": ["security", "encryption"]
    }
  ],
  "pagination": {
    "total": 145,
    "page": 1,
    "limit": 10
  }
}

Retrieve a Single Decision

GET /v1/decisions/:slug

Fetches the complete details of a specific decision identified by its unique slug. This includes the full description, reasoning, category, and current enforcement status. Use this endpoint when you need to display the deep context of a decision within your own tools.

Tip: The slug is a URL-friendly version of the title, but you can also use the unique decision ID (prefixed with dec_) in this endpoint.

Example Request

GET /v1/decisions/standardize-on-aes-256

GET /v1/decisions/standardize-on-aes-256

GET /v1/decisions/standardize-on-aes-256

GET /v1/decisions/standardize-on-aes-256

Example Response

{
  "id": "dec_12345",
  "slug": "standardize-on-aes-256",
  "title": "Standardize on AES-256 for Data at Rest",
  "description": "All sensitive data must be encrypted using AES-256 at the application layer.",
  "reasoning": "Compliance requirements for SOC 2 and internal security mandates.",
  "state": "accepted",
  "category": "Security",
  "priority": "high",
  "tags": ["security", "encryption"],
  "metadata": {
    "enforced_in_ide": true,
    "linked_memories_count": 3
  }
}

{
  "id": "dec_12345",
  "slug": "standardize-on-aes-256",
  "title": "Standardize on AES-256 for Data at Rest",
  "description": "All sensitive data must be encrypted using AES-256 at the application layer.",
  "reasoning": "Compliance requirements for SOC 2 and internal security mandates.",
  "state": "accepted",
  "category": "Security",
  "priority": "high",
  "tags": ["security", "encryption"],
  "metadata": {
    "enforced_in_ide": true,
    "linked_memories_count": 3
  }
}

{
  "id": "dec_12345",
  "slug": "standardize-on-aes-256",
  "title": "Standardize on AES-256 for Data at Rest",
  "description": "All sensitive data must be encrypted using AES-256 at the application layer.",
  "reasoning": "Compliance requirements for SOC 2 and internal security mandates.",
  "state": "accepted",
  "category": "Security",
  "priority": "high",
  "tags": ["security", "encryption"],
  "metadata": {
    "enforced_in_ide": true,
    "linked_memories_count": 3
  }
}

{
  "id": "dec_12345",
  "slug": "standardize-on-aes-256",
  "title": "Standardize on AES-256 for Data at Rest",
  "description": "All sensitive data must be encrypted using AES-256 at the application layer.",
  "reasoning": "Compliance requirements for SOC 2 and internal security mandates.",
  "state": "accepted",
  "category": "Security",
  "priority": "high",
  "tags": ["security", "encryption"],
  "metadata": {
    "enforced_in_ide": true,
    "linked_memories_count": 3
  }
}

Create a Decision

POST /v1/decisions

Creates a new decision in the Draft state. This is the entry point for codifying organizational judgment. While the title and description are required, providing detailed reasoning is highly recommended, as this reasoning is what Hopper uses to explain the decision to other developers later.

Request Body Fields

• title (string, required): A concise summary of the decision.

• description (string, required): The explicit rule or commitment being made.

• reasoning (string, optional): The justification and context behind the decision. This is preserved as the primary Memory associated with the decision.

• category (string, optional): The functional area (e.g., Infrastructure, API Design).

• tags (array of strings, optional): Keywords for organization and searching.

• priority (string, optional): The importance level (low, medium, high, critical).

Example Request

POST /v1/decisions
{
  "title": "Use GraphQL for External APIs",
  "description": "All new public-facing APIs must be implemented using GraphQL.",
  "reasoning": "To provide better flexibility for frontend consumers and reduce over-fetching.",
  "category": "Architecture",
  "tags": ["api", "graphql", "frontend"]
}

POST /v1/decisions
{
  "title": "Use GraphQL for External APIs",
  "description": "All new public-facing APIs must be implemented using GraphQL.",
  "reasoning": "To provide better flexibility for frontend consumers and reduce over-fetching.",
  "category": "Architecture",
  "tags": ["api", "graphql", "frontend"]
}

POST /v1/decisions
{
  "title": "Use GraphQL for External APIs",
  "description": "All new public-facing APIs must be implemented using GraphQL.",
  "reasoning": "To provide better flexibility for frontend consumers and reduce over-fetching.",
  "category": "Architecture",
  "tags": ["api", "graphql", "frontend"]
}

POST /v1/decisions
{
  "title": "Use GraphQL for External APIs",
  "description": "All new public-facing APIs must be implemented using GraphQL.",
  "reasoning": "To provide better flexibility for frontend consumers and reduce over-fetching.",
  "category": "Architecture",
  "tags": ["api", "graphql", "frontend"]
}

Update a Decision

PATCH /v1/decisions/:slug

Allows for the modification of a decision's core fields. To maintain the integrity of the Knowledge Graph, updates are only permitted while a decision is in the Draft or Pending state. Once a decision is Accepted, it is considered a frozen commitment; any changes thereafter must be handled via deprecation and the creation of a new decision to ensure full traceability.

Example Request

PATCH /v1/decisions/use-graphql-for-external-apis
{
  "priority": "high",
  "tags": ["api", "graphql", "standards"]
}

PATCH /v1/decisions/use-graphql-for-external-apis
{
  "priority": "high",
  "tags": ["api", "graphql", "standards"]
}

PATCH /v1/decisions/use-graphql-for-external-apis
{
  "priority": "high",
  "tags": ["api", "graphql", "standards"]
}

PATCH /v1/decisions/use-graphql-for-external-apis
{
  "priority": "high",
  "tags": ["api", "graphql", "standards"]
}

Submit for Review

POST /v1/decisions/:slug/submit

Transitions a decision from Draft to Pending. This action signals to the rest of the team that the decision is ready for formal evaluation. At this stage, Hopper will automatically scan the Knowledge Graph to identify any potential contradictions with existing Accepted decisions.

Tip: It is best practice to review the /conflicts endpoint immediately after submitting to ensure your new decision doesn't contradict established organizational patterns.

Accept a Decision

POST /v1/decisions/:slug/accept

Transitions a decision from Pending to Accepted. This is the most significant state change in the Hopsule ecosystem. Upon acceptance, the decision is broadcast to all Context Packs and becomes active in the Hopsule IDE Extension. This endpoint requires elevated permissions, as it represents a formal organizational commitment.

Once accepted, the decision’s constraints are enforced. If a developer writes code that violates this decision, Hopsule will surface a warning directly in their editor, ensuring that "enforcement is remembrance."

Deprecate a Decision

POST /v1/decisions/:slug/deprecate

Moves an Accepted decision to the Deprecated state. Decisions in Hopsule are never deleted; they are preserved as part of the organizational memory. When deprecating, you must provide a reason. This reason is vital for future team members to understand why a previously accepted standard was abandoned.

Request Body

• reason (string, required): A detailed explanation of why this decision is no longer valid or what has replaced it.

Example Request

POST /v1/decisions/use-graphql-for-external-apis/deprecate
{
  "reason": "Transitioning to a federated architecture where REST is more suitable for our specific microservices overhead."
}

POST /v1/decisions/use-graphql-for-external-apis/deprecate
{
  "reason": "Transitioning to a federated architecture where REST is more suitable for our specific microservices overhead."
}

POST /v1/decisions/use-graphql-for-external-apis/deprecate
{
  "reason": "Transitioning to a federated architecture where REST is more suitable for our specific microservices overhead."
}

POST /v1/decisions/use-graphql-for-external-apis/deprecate
{
  "reason": "Transitioning to a federated architecture where REST is more suitable for our specific microservices overhead."
}

Version History

GET /v1/decisions/:slug/history

Hopsule maintains a complete, immutable audit trail of every change made to a decision. This endpoint returns a list of versions, including who made the change, what fields were modified, and the timestamp of the event. This ensures total transparency and accountability for the organization's governance layer.

Conflict Detection

GET /v1/decisions/:slug/conflicts

One of the most powerful features of Hopsule is its ability to detect when decisions contradict one another. This endpoint queries the Knowledge Graph to find Accepted decisions that may overlap or conflict with the specified decision. This is particularly useful during the Pending state to prevent the creation of fragmented or confusing standards.

Important: Conflict detection is advisory. It highlights potential issues for human reviewers to resolve, reinforcing the philosophy that Hopsule assists organizational judgment rather than replacing it.

Linked Memories

GET /v1/decisions/:slug/memories

Decisions are often born from a series of events, discussions, or lessons learned. These are captured as Memories. This endpoint retrieves all append-only memory entries linked to a specific decision. By reviewing linked memories, a developer can understand the "why" behind the "what," providing the necessary context to follow the decision effectively.

Because memories are append-only and never deleted, this endpoint provides a window into the historical evolution of the team's thinking over months or years.

Error Handling

The Hopsule API uses standard HTTP response codes to indicate the success or failure of an API request. In the event of an error, the response body will contain a machine-readable code and a human-readable message to assist in debugging.

Best Practices for API Integration

To get the most out of the Hopsule Decisions API, we recommend following these integration patterns:

1. Automate Draft Creation: Use the API to create Draft decisions based on triggers in your communication tools. For example, when a specific tag is used in an architectural discussion, a draft can be automatically generated for a human to refine later.

2. Sync with CI/CD: Use the Hopsule CLI or the API within your deployment pipelines to verify that the current project state does not violate any Accepted decisions. This adds an extra layer of governance before code reaches production.

3. Visualizing the Brain: Use the /decisions and /conflicts endpoints to build custom visualizations of your team's decision landscape, helping new hires understand the architectural "gravity" of the organization.

4. Context Preservation: Always include the reasoning field when creating decisions via the API. This ensures that the Memory layer is populated from day one, making the decision more resilient to the passage of time.

By treating decisions as data, your engineering organization can move faster with the confidence that its most important choices are preserved, enforced, and remembered.