Hopsule API: Overview and Authentication

Introduction to the Hopsule API

The Hopsule API serves as the programmatic gateway to your organization's decision-first memory system. It is designed to allow engineering teams to integrate the preservation and enforcement of organizational judgment directly into their custom workflows, internal tools, and automated pipelines. By providing structured access to Decisions, Memories, and Context Packs, the API ensures that the reasoning behind your architecture and the constraints of your environment remain accessible and enforceable even outside the primary Hopsule interfaces.

Unlike traditional data interfaces that focus on simple information retrieval, the Hopsule API is built around the philosophy of governance and remembrance. It provides the necessary infrastructure to programmatically transition decisions through their lifecycle—from Draft to Accepted—and to append context to the immutable memory stream. This ensures that every automated action or external integration respects the established authority of the team’s collective commitments. Whether you are building custom CI/CD checks or integrating Hopsule with third-party orchestration tools, the API maintains the integrity of your organizational context.

Important: The Hopsule API is a read-write interface for managing the lifecycle of decisions and memories, but it is not a replacement for Hopper, our advisory AI assistant. While the API allows you to programmatically create and query records, the nuanced interpretation of conflicts and the generation of decision drafts from natural language remain the domain of Hopper and the Hopsule Dashboard.

Base URL and API Versioning

All API requests are served over HTTPS to ensure the security and privacy of your organization's context. The Hopsule API follows a versioned structure to provide stability and backward compatibility as the platform evolves. The current stable version of the API is v1. Using versioned endpoints ensures that your integrations continue to function correctly even as new features and capabilities are added to the Hopsule ecosystem.

The base URL for all API calls is: https://api.hopsule.com/v1

Requests made to the root or unversioned endpoints will return a 404 Not Found error or a redirect to the current stable documentation. We recommend hardcoding the version prefix in your client implementations to avoid unexpected behavior during platform updates. When we introduce breaking changes, a new version prefix (e.g., /v2) will be released, and the previous version will enter a deprecation period as outlined in our versioning policy at the end of this document.

Authentication Methods

Hopsule prioritizes the security of your organizational memory through robust authentication mechanisms. Every request to the Hopsule API must be authenticated. We support two primary methods of authentication depending on your use case: API Keys for long-lived programmatic access and JWT Tokens for user-delegated sessions or short-lived integrations. Failure to provide valid credentials will result in a 401 Unauthorized response.

API Keys

API Keys are the preferred method for server-to-server integrations, CI/CD pipelines, and custom internal tools. These keys are associated with specific projects or organizations and carry the authority granted to the service account they represent. You can generate and manage these keys within the Hopsule Dashboard under the Settings > API Access section. API keys should be treated as highly sensitive credentials and never committed to version control.

To authenticate using an API key, include the X-API-Key header in your HTTP requests:

Tip: We recommend using different API keys for different environments (e.g., staging vs. production) to maintain a clear audit trail and to limit the blast radius in the event of a credential leak.

JWT Tokens (Bearer Authentication)

For integrations that act on behalf of a specific user, such as custom frontend extensions or interactive scripts, Hopsule supports JSON Web Tokens (JWT). These tokens are typically obtained through the Hopsule OAuth flow or by exchanging a valid session from the Hopsule Dashboard. JWTs are short-lived and provide a secure way to delegate authority without exposing long-term credentials.

To authenticate using a JWT, use the standard Authorization header with the Bearer scheme:

Request and Response Formats

The Hopsule API is built on REST principles and uses JSON (JavaScript Object Notation) as the primary format for both requests and responses. This ensures compatibility across a wide range of programming environments and makes the data easily consumable by modern engineering tools. Consistency in data structure is a core requirement for maintaining the reliability of your organizational memory.

Request Format

For all POST, PUT, and PATCH requests, the Hopsule API expects a JSON-encoded body. You must include the Content-Type: application/json header in these requests to ensure the server correctly interprets the payload. Fields should be provided in camelCase as per the API specification. Any unexpected fields in the request body will be ignored by the server to maintain forward compatibility.

Example request headers:

• Content-Type: application/json

• Accept: application/json

• X-API-Key: [YOUR_API_KEY]

Response Format

The Hopsule API returns a standardized JSON envelope for all responses. This envelope structure ensures that clients can consistently parse data, metadata, and error information regardless of the specific endpoint being called. A typical response object contains three top-level keys: data, meta, and errors.

By wrapping all responses in this envelope, Hopsule provides a predictable interface for developers, allowing for centralized error handling and easier debugging of complex integrations.

Pagination

To ensure high performance and stability when retrieving large volumes of Memories or Decisions, the Hopsule API employs cursor-based pagination. Unlike traditional offset-based pagination, cursor-based navigation is resilient to data changes (such as new entries being appended to a Context Pack) and provides a more consistent experience for append-only memory systems.

When a collection endpoint is queried, the API returns a subset of the results along with a next_cursor in the meta object. To fetch the next set of results, you must include this cursor in the cursor query parameter of your subsequent request. If the next_cursor is null, you have reached the end of the collection.

The default page size is 25 items, but this can be adjusted using the limit parameter. The maximum allowed limit is 100 items per request. This constraint ensures that response times remain low and that the Knowledge Graph remains performant even as your organizational memory grows over time.

Rate Limiting

Hopsule enforces rate limits to maintain the availability and reliability of the API for all users. These limits are applied based on the plan tier of your organization. When a rate limit is exceeded, the API will return a 429 Too Many Requests status code, and subsequent requests will be blocked until the limit resets.

Rate limits are calculated on a per-minute rolling window. The following table outlines the standard limits for each plan:

Important: Every API response includes headers that inform you of your current rate limit status. We strongly recommend that your client implementations monitor these headers to avoid being throttled. The headers are: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (a Unix timestamp indicating when the limit will reset).

Error Handling

The Hopsule API uses standard HTTP status codes to indicate the success or failure of an API request. When an error occurs, the response body will contain a detailed errors array within the standard JSON envelope to help you diagnose and resolve the issue. Each error object includes a code, a human-readable message, and, where applicable, a field property indicating which part of the request caused the error.

Common HTTP Status Codes

• 200 OK: The request was successful, and the requested data is in the response body.

• 201 Created: The resource (e.g., a new Decision) was successfully created.

• 400 Bad Request: The request was malformed or failed validation. Check the errors array for details.

• 401 Unauthorized: Authentication failed or was not provided.

• 403 Forbidden: The authenticated user or key does not have the necessary permissions for this action.

• 404 Not Found: The requested resource does not exist.

• 429 Too Many Requests: You have exceeded your rate limit.

• 500 Internal Server Error: An unexpected error occurred on the Hopsule servers.

For 400 Bad Request errors related to decision enforcement, the error message will often provide context on why a decision cannot be accepted—for example, if it contradicts an existing Accepted decision in the same Context Pack. This programmatic enforcement ensures that your organizational authority remains consistent across all interfaces.

API Versioning and Deprecation Policy

We understand that the Hopsule API is a critical component of your engineering infrastructure. As such, we follow a strict versioning and deprecation policy to provide predictability. Major versions of the API (e.g., v1, v2) are supported for at least 12 months after the release of a subsequent version. During this period, the older version is considered "Deprecated" but remains fully functional.

When a version is officially deprecated, we will notify organization administrators via the Hopsule Dashboard and email. We will also include a Warning header in API responses for the deprecated version. Once the support period ends, the version is "Retired," and all requests to those endpoints will return a 410 Gone error. We strive to make transitions between versions as seamless as possible by providing detailed migration guides and updated documentation for each release.

Testing with cURL

The quickest way to verify your API access and explore the structure of your organizational memory is by using cURL from your terminal. This allows you to interact with the Hopsule API without writing any code. Below are examples of common operations using the v1 endpoints.

Retrieve All Decisions

To fetch a list of decisions within your organization, use a GET request. This example assumes you are using an API key for authentication:

Create a New Memory Entry

To append a new memory to the immutable context stream, use a POST request with a JSON body. Remember that memories are append-only and serve as the foundational reasoning for your decisions:

Tip: You can find your context_pack_id by navigating to the specific Capsule in the Hopsule Dashboard or by listing all capsules via the /v1/capsules endpoint. Using the API to automate the capture of these memories ensures that your Knowledge Graph remains a living reflection of your engineering reality.

Next Steps

Now that you understand the fundamentals of the Hopsule API and how to authenticate your requests, you can begin integrating Hopsule's decision and memory layer into your own systems. We recommend exploring the following resources to deepen your integration:

• Decisions API Reference: Detailed documentation on managing the decision lifecycle programmatically.

• Memories API Reference: Learn how to build append-only context streams from external data sources.

• Context Packs & Capsules: Understand how to bundle and share decisions across different projects.

• Hopsule CLI: For a higher-level programmatic interface that wraps the API for terminal use.

By leveraging the Hopsule API, you are moving beyond simple documentation and toward a robust system of organizational remembrance and governance. If you encounter any issues or require higher rate limits for your enterprise deployment, please contact our support team through the Hopsule Dashboard.