MindEvent API

The standard interface for sending real-world events into MindEntry.

MindEvent API v1 allows external systems to send meaningful real-world events into the Mental Background OS.

A meeting can finish. A focus session can start. A commute can end. A webhook can fire.

Those events can enter MindEntry as MindEvents, where they may surface as a Recipe or CogniHack suggestion. Nothing runs automatically. The user remains in control.

What Is a MindEvent?

A MindEvent is a structured description of something that happened outside the user’s immediate thought input.

Unlike typing into MindEntry or sharing selected text through the Share Sheet, a MindEvent begins from reality: a calendar event, automation, shortcut, webhook, NFC tag, or external system.

MindEntry receives the event, interprets it locally, and may suggest a mental state transition.

Reality

↓

MindEvent API

↓

MindEntry

↓

Mental State Movement

Endpoint

Use the following endpoint to send a MindEvent:

POST https://mindbebop-webhook.kentaro-yamauchi99.workers.dev/mindevent

The endpoint accepts JSON and returns a normalized MindEvent plus a Universal Link that can open MindEntry.

Authentication

MindEvent API requires an API key.

Send the key using either authorization method:

Authorization: Bearer <API_KEY>

or:

X-MindEvent-Key: <API_KEY>

Requests without a valid API key are rejected.

Request Headers

Authorization: Bearer <API_KEY>
Content-Type: application/json

Request Body

The event field is required.

The title, source, context, and payload fields are optional.

{
  "event": "meeting_finished",
  "title": "Weekly Team Sync",
  "source": "webhook",
  "context": "team",
  "payload": {
    "duration": "65",
    "location": "office"
  }
}

Fields

event — The MindEvent identifier. Required.
title — Human-readable title shown in MindEntry when available.
source — The external source that sent the event.
context — Optional context such as team, home, sales, commute, or focus.
payload — Optional key-value metadata for future use.

Supported Event Vocabulary

MindEvent API v1 currently defines the following standard events.

Additional standardized events may be introduced in future versions while preserving compatibility with existing integrations.

Work

meeting_finished
presentation_finished
workday_started
workday_finished
task_started
task_finished
deep_work_started
deep_work_interrupted
break_finished

Calendar

calendar_reminder

Location

arrived_home
left_home
commute_started
commute_finished

Personal

focus_started
focus_ended
waiting_for_reply
bedtime
woke_up
feeling_stuck

Successful Response

A successful request returns the normalized MindEvent, a Universal Link, and a custom URL fallback.

{
  "success": true,
  "version": 1,
  "mindEvent": {
    "version": 1,
    "event": "meeting_finished",
    "title": "Weekly Team Sync",
    "source": "webhook",
    "context": "team",
    "payload": {
      "duration": "65",
      "location": "office"
    },
    "known": true,
    "receivedAt": "2026-06-29T02:12:34.520Z"
  },
  "universalLink": "https://mindbebop.com/mindevent?event=meeting_finished&source=webhook&title=Weekly+Team+Sync&context=team",
  "mindEntryURL": "mindentry://mindevent?event=meeting_finished&source=webhook&title=Weekly+Team+Sync&context=team"
}

Universal Link

The universalLink field is the preferred way to open MindEntry.

On iPhone, opening the link can launch MindEntry directly and deliver the MindEvent to the app.

If MindEntry is not installed, the link falls back to a web page.

https://mindbebop.com/mindevent?event=meeting_finished&source=webhook&title=Weekly+Team+Sync

Fallback URL

The mindEntryURL field is provided as a fallback and for debugging.

New integrations should prefer the Universal Link.

mindentry://mindevent?event=meeting_finished&source=webhook&title=Weekly+Team+Sync

HTTP Status Codes

200 — MindEvent accepted.
400 — Invalid JSON or missing event.
401 — Unauthorized. Missing or invalid API key.
404 — Endpoint not found.
405 — Method not allowed.

curl Example

curl -X POST \
https://mindbebop-webhook.kentaro-yamauchi99.workers.dev/mindevent \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "event": "meeting_finished",
  "title": "Weekly Team Sync",
  "source": "webhook",
  "context": "team",
  "payload": {
    "duration": "65",
    "location": "office"
  }
}'

Health Check

The root endpoint returns API status and usage information.

GET https://mindbebop-webhook.kentaro-yamauchi99.workers.dev/

Example response:

{
  "service": "MINDBEBOP",
  "version": 1,
  "endpoint": "MindEvent webhook receiver",
  "status": "alive",
  "preferredDelivery": "universalLink"
}

What It Does Not Do

It does not auto-run Recipes.
It does not bypass user confirmation.
It does not read private thoughts.
It does not expose internal Recipe data.
It does not require third parties to understand MindEntry internals.

The API sends a structured event into MindEntry. What happens next remains under the user’s control.

Versioning

This page describes MindEvent API v1.

The top-level version field describes the API contract. The nested mindEvent.version field describes the MindEvent payload version.

Future versions may add fields while preserving the core contract.

Access

API key access is currently limited.

For access or integration questions, contact:

support@mindbebop.com

MindEvent API is not automation itself.

It is the event language that lets reality speak to the Mental Background OS.