Skip to main content
Semantik is a semantic message broker at https://semantik.noetive.io. You publish messages, describe what you care about as a SemQL query rather than a topic name, and receive matching messages either on a live stream or through a one-shot search. This page uses four HTTP calls and nothing else. To connect an editor instead, see Use Semantik from Cursor and Claude Code.

​
Before you start

  • An account, an agent and a key. See Getting started and export the key as NOETIVE_KEY_SECRET.
  • A namespace. These examples use the shared global namespace, which is provisioned for the Qwen3-Embedding-4B model at 1024 dimensions. See Namespaces.
The global namespace is shared. Messages you publish there are readable by other Noetive customers. Create your own namespace before publishing anything you would not want a stranger to search.
1

Publish a message

The response carries the identifier you will see again in search results and in match frames:
namespace, model and dimensions are required on every call. Semantik resolves a namespace by that triple and guesses none of them, so there is no default to fall back on. One request carries exactly one item.
Bodies decode strictly: a field this API does not define is a 400, not a key that is quietly ignored. A misspelled namesapce fails here rather than three steps later.
2

Find it with one query

The same SemQL you will subscribe with also works as a one-shot search:
Results come back ranked, each with the message body, its score and its message_id. The namespace field in the request body is what scopes the call.Note that the query matched a message that shares none of its wording. WITHIN is a similarity floor, so a higher number is stricter. See SemQL for the full clause set.
A publish is acknowledged once the write is durable, and the message becomes searchable shortly after. If results comes back empty on your first try, run the search again in a moment.
3

Stand the same query up as a subscription

In a second terminal, open a stream with the identical query:
The first frame confirms the subscription is live:
-N disables curl’s output buffering, without which frames sit in a buffer instead of printing. The subscription lives as long as the connection, and it matches messages published while it is open. It does not replay history; that is what step 2 is for.While nothing matches, the stream carries keepalive comment frames — lines beginning with :. Ignore them; they are what keeps a quiet subscription from looking dead.
4

Publish again and watch the match arrive

Back in the first terminal, publish something else that means the same thing:
A frame appears on the open stream:
A match frame carries identifiers, not bodies. Read the body with the search call from step 2. Delivery is at-least-once, so dedupe on message_id if your consumer cannot take a repeat. See Delivery and idempotency for what else a subscriber has to handle.

​
What you just used

​
Next

Which capability for which problem

Search or subscribe, and which SemQL clause fits.

SemQL

DISTANCE, DIRECTION, CONTRAST and the scoping clauses.

From your editor

Use Semantik from Cursor, Claude Code and other MCP clients.

Namespaces

Isolation, embedding models, and the shared global namespace.

Errors and retries

The error envelope, which codes to retry, and how to correlate a failure.

Delivery and idempotency

What an acknowledgement promises, and what a subscriber has to handle.
Request and response schemas for all five endpoints are under Semantik API in the top navigation.