Blissbook for Developers

REST API

Overview

Pull your compliance data over HTTPS: the audit log, signatures and the PDFs behind them, your saved reports, and the published content a person can see. Every endpoint is a GET against your own subdomain.

API access is enabled per organization. If a request comes back 403, ask your Blissbook administrator to have it turned on for your account.

Authentication

Every request is authenticated with HTTP Basic Auth: your API key’s Access Key ID is the username and its Secret Access Key is the password. To generate a key:

1. Open Settings → Tech Setup in Blissbook.
2. Find the section for Blissbook’s API.
3. Click Generate an API Key.
4. Copy the Access Key ID and Secret Access Key.
5. Save the Secret Access Key right away, because Blissbook only shows it once.

Rate Limiting

Requests are limited to 120 per minute, counted against your API key on the API and against the account you authorized on the MCP server. The exports cost more than the rest, so the signature PDFs and the event export share a tighter limit of 60 per minute out of that same allowance. Blissbook responds with a 429 Too Many Requests error if you exceed either.

Error Handling

An error answers with the HTTP status below and the same JSON body every time: message says what went wrong, statusCode and statusMessage repeat the status, and code names the specific failure when there is one to name.

{
  "message": "Invalid API key",
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "code": "INVALID_API_KEY"
}

MCP Server

Overview

The MCP server speaks Streamable HTTP. Add the endpoint below to any MCP client and it will walk you through authorizing your Blissbook account.

Every tool the server can expose is listed below. The tools your client actually sees depend on your plan and your permissions in Blissbook, so a given connection may offer fewer than these.

Authentication

The server authenticates with OAuth 2.1, so there is no key to copy anywhere: point your client at the endpoint above, it registers itself against the discovery metadata, and Blissbook asks you to sign in and authorize it. The connection then acts as you, so every tool sees exactly the data your own Blissbook permissions allow. Revoking your authorization cuts it off.

Rate Limiting

Requests are limited to 120 per minute, counted against your API key on the API and against the account you authorized on the MCP server. The exports cost more than the rest, so the signature PDFs and the event export share a tighter limit of 60 per minute out of that same allowance. Blissbook responds with a 429 Too Many Requests error if you exceed either.

Error Handling

An error answers with the HTTP status below and the same JSON body every time: message says what went wrong, statusCode and statusMessage repeat the status, and code names the specific failure when there is one to name.

{
  "message": "Invalid API key",
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "code": "INVALID_API_KEY"
}

The MCP server speaks JSON-RPC, so what the transport itself rejects comes back in a JSON-RPC envelope rather than that body: an unauthorized request carries error code -32001 alongside a WWW-Authenticate header naming the discovery metadata, and arguments that fail a tool's schema come back as -32602 (Invalid params) naming the argument.

A tool that runs and then fails answers with an error result instead, carrying the same message. Your client hands that to the model, which can correct the call and try again.

Use Cases

Connect your Chatbot to Blissbook

To answer your employees’ questions from your chatbot, connect to Blissbook once and let the chatbot read as whoever is asking the question. Pass asPerson to any Audience Members tool and the answer comes back personalized to that person.

Reading as another person is a permission, and the connection has permissions of the Blissbook account that authorized it. A manager’s account can already read as anyone who reports to them; reading as anyone in your organization takes the Reporting Only team role (or Team Owner). So authorize the connection as an account that exists for the integration rather than as one of your people:

1. Create a person in Blissbook for the integration, with a name you’ll recognize, on an email address your IT team owns rather than an individual’s.
2. Give that person the Reporting Only team role. It grants reporting across your Documents and nothing else: no editing, no publishing.
3. Sign in as that account, then add the MCP endpoint above to your chatbot and complete the authorization prompt as that account.
4. Have your chatbot pass the asking employee as asPerson: exactly one of email, employeeId, or personId, whichever your chatbot already knows about them.

Because the account isn’t a person, nobody’s departure breaks the integration and the email address behind it is a credential, so restrict it the way you would any shared admin account. To cut the connection off, remove the Reporting Only role: permissions are checked on every call, so the next request fails even if the chatbot still holds a token.

From there, there are two ways to get the content into your chatbot’s answer.

Let Blissbook do the work. Call search_live_content with the employee’s question and it returns the most relevant passages, already personalized to the person in asPerson. Each one carries a relevance score and the Document Section or Policy it came from, so your chatbot can cite where the answer lives. Chunking, embedding, and audience filtering stay on our side; your chatbot only writes the answer. This is the shorter path, and it needs the Audience Chatbot enabled for the organization, since that setting is what embeds your content in the first place. Without it the call comes back 403.

Fetch the content yourself. list_live_content returns the whole table of contents a person can access, and get_live_content reads the HTML content up to 20 of those ids per call. Use it to index the content in your own vector store, or to hand a model an entire policy rather than a passage of one. IMPORTANT: every tool answers as a specific person, not your organization at large. An index built from one person’s content is wrong for the next person.

Resources

Events

Blissbook records an event when somebody signs in, when somebody is granted a role, when content is published or signed, and for every call the API and the MCP server serve. Everything recorded is named below — if something isn’t here, no event is recorded for it. Read them with the List Events endpoint or the list_events tool.