Skip to main content
Semantik has four calls. Which one you want follows from one question: are you asking about what already happened, or asking to be told when something happens?

​
Act when something means X

Open a subscription and hold the connection. Every message published while it is open is matched against your query, and each match arrives as a frame carrying a message_id and a score. The frame does not carry the body. Fetch it with POST /v1/search when you need it, or act on the metadata alone when the identifier is enough. Two facts that shape the design of anything built on this:
  • A subscription matches only messages published after it is registered. There is no replay. Pair it with a search if you also need what came before.
  • Delivery is at-least-once. Dedupe on message_id if a repeat would be harmful.

​
Shared context across parallel agents

Each agent publishes what it finds, and each agent opens a subscription describing what would matter to it. The publisher names no recipients, and the subscriber names no publisher, so an agent added later starts receiving relevant messages without anything being reconfigured. This is the pattern where CONTRAST earns its place. “Anything about a change to a file I depend on, but not routine status updates” is one clause, where a topic scheme would need two topics and a convention nobody enforces.

​
Routing when you do not know the taxonomy

A topic broker asks the publisher to label content before the content exists. When that label is the thing you are missing, invert it: let the subscriber’s predicate decide. Publishers stay unchanged. A new interest is a new query, not a new topic and a publisher deploy.

​
Find what already exists

POST /v1/search runs the same SemQL against stored messages and returns ranked results with their bodies. Use it to backfill context, to fetch the body behind a match frame, and to check whether a question has already been answered before spending tokens answering it again.

​
Which clause fits

WITHIN is a similarity floor, so higher is stricter. CONE is a half-angle, so lower is stricter. They run in opposite directions, which is the one thing worth checking twice. POST /v1/lint validates a query and needs no API key, so check a query before you stand it up.

​
The decision in one line

“What already exists that looks like X” is search. “Tell me as soon as something looks like X” is subscribe. Systems that need both use both, with the same query string.