Signals

Overview

Not everything in your day comes from a person. The issue that was assigned to you while you slept, the alert your error tracker raised at two in the morning — the systems you work with have things to tell you too. A signal is a source pushed into your inbox by something outside Mindnodes: a GitHub issue, an alert from your error tracker, a row from a system your team runs. It queues beside your mail, because to your morning it is the same kind of thing.

Mindnodes defines the contract and the outside world pushes. There is no per-integration code, which is why a signal from a tool nobody here has heard of behaves exactly like the rest.

Basics

What a signal carries

• A kind — what sort of thing it is, decided by whoever pushes it.
• A reference — the identity on the other side, so the same thing pushed twice is one item, not two.
• A title , an optional link back to where it came from, and an optional body — one markdown document holding whatever the pusher has to say. Headings, lists, tables and code all survive, so a payload can be laid out to be read rather than flattened into a sentence.

Pushing one

One address, one call: POST /api/signals , authenticated with an API key as a bearer token. You make a key under Settings → Integrations , which is also where the address is shown ready to copy.

curl -X POST https://mindnodes.com/api/signals \
  -H "Authorization: Bearer $MINDNODES_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "kind": "github_issue",
        "reference": "acme/app#42",
        "title": "Build fails on main",
        "url": "https://github.com/acme/app/issues/42",
        "content": "The `deploy` job failed **3 times** in a row.\n\n| Field | Value |\n| --- | --- |\n| Severity | high |\n| Assignee | you |"
      }'

The pair kind + reference is the identity, so pushing the same pair again updates the item you already have instead of adding a second one — a poller can re-push on every run without filling your inbox. That also means a re-push does not, by itself, ask for your attention again: add ?inbox=1 when it should, and leave it off when you are only healing state.

Retracting one

When what you pushed stops being true — the alert resolved, the issue closed, the run went green — the same system can take it back. Same address, same identity pair:

curl -X DELETE https://mindnodes.com/api/signals \
  -H "Authorization: Bearer $MINDNODES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "github_issue", "reference": "acme/app#42"}'

The item leaves your inbox and comes off any node you had hung it on — the node itself stays. Retracting something that is already gone, because you retried or because you had already thrown it away yourself, is not an error: the answer is the same either way.

Attaching files and screenshots

A signal's body can carry files — the screenshot on a bug report, the PDF an invoice system generated, the log a failing job wrote. It takes two calls, because bytes and JSON do not travel together: upload the file first, then refer to what you uploaded.

curl -X POST https://mindnodes.com/api/media \
  -H "Authorization: Bearer $MINDNODES_KEY" \
  -F "[email protected]"
# → {"data": {"id": "01J8...", ...}}

Put that id in the body where the file belongs, and it renders inline — an image as an image, a document as something to open:

"content": "The layout breaks at 320px:\n\n<embed media=\"01J8...\" />"

A file has to be uploaded with a key of your own. A body may only point at media that is already in your library, never at an address written into the payload itself — so a signal can only show you something that key was allowed to put there in the first place.

What happens when one arrives

It queues in the Inbox beside your mail and your events, your second brain reads it, and you settle it the same way: hang it on a node, archive it, or ask for another look.

Hang it on a node

The same Nodes field as every other item. An issue about a client goes on the client; a run of alerts about one service goes on the node for that service.

Which node should it be?

A signal arrives without a say in where it belongs, so the judgement is entirely yours — and it is the same two questions every other kind asks.

• Does something go in, or come out? A pushed issue asks something of you and leaves a decision behind: it belongs on something you keep. A green build is a receipt — nothing goes in, nothing comes out. Archive it unlinked.
• What is it about? The project, the component, the customer it concerns — not the system that pushed it. A node named "Sentry" or "GitHub" is a folder wearing a node's name: it groups by where things came from, which is the one thing the signal already says on its own.

A signal that keeps arriving about the same thing is the sign that thing deserves a node: the component with three alerts this month is something you are working on, whether or not you have written it down yet.

FAQ

What can push a signal?

Anything that can make an HTTP request and hold a key: a CI step, a webhook forwarder, a cron job, a script on your own machine. The kinds that exist are the kinds someone has wired up.

Does a signal open the thing it came from?

Yes, when the push carried a link — it opens the issue or the alert where it lives.