> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noetive.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantik quickstart

> Publish a message, find it by meaning, and stream matches as they arrive.

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](/guides/mcp-setup).

## Before you start

* **An account, an agent and a key.** See [Getting started](/guides/quickstart) 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](/semantik/namespaces).

<Warning>
  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.
</Warning>

<Steps>
  <Step title="Publish a message">
    ```bash theme={null}
    curl -sS https://semantik.noetive.io/v1/publish -H "Authorization: Bearer $NOETIVE_KEY_SECRET" -H "Content-Type: application/json" -d '{"namespace":"global","model":"Qwen3-Embedding-4B","dimensions":1024,"items":[{"text":"The payment gateway started timing out on checkout at 14:02 UTC."}],"metadata":{"source":"quickstart"}}'
    ```

    The response carries the identifier you will see again in search results and in match frames:

    ```json theme={null}
    {"message_id":"msg_01jd7a21de40f1b2c493","epoch":7,"seq":149}
    ```

    <Note>
      `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.
    </Note>

    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.
  </Step>

  <Step title="Find it with one query">
    The same SemQL you will subscribe with also works as a one-shot search:

    ```bash theme={null}
    curl -sS https://semantik.noetive.io/v1/search -H "Authorization: Bearer $NOETIVE_KEY_SECRET" -H "Content-Type: application/json" -d '{"namespace":"global","model":"Qwen3-Embedding-4B","dimensions":1024,"query":"MATCH DISTANCE(\"payment gateway timing out during checkout\") WITHIN 0.5 LIMIT 5"}'
    ```

    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](/semantik/query-language) for the full clause set.

    <Info>
      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.
    </Info>
  </Step>

  <Step title="Stand the same query up as a subscription">
    In a second terminal, open a stream with the identical query:

    ```bash theme={null}
    curl -sS -N https://semantik.noetive.io/v1/subscribe -H "Authorization: Bearer $NOETIVE_KEY_SECRET" -H "Content-Type: application/json" -d '{"namespace":"global","model":"Qwen3-Embedding-4B","dimensions":1024,"query":"MATCH DISTANCE(\"payment gateway timing out during checkout\") WITHIN 0.5"}'
    ```

    The first frame confirms the subscription is live:

    ```text theme={null}
    event: subscribed
    data: {"subscription_id":"sub_8f2c4e1a9b3d"}
    ```

    `-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.
  </Step>

  <Step title="Publish again and watch the match arrive">
    Back in the first terminal, publish something else that means the same thing:

    ```bash theme={null}
    curl -sS https://semantik.noetive.io/v1/publish -H "Authorization: Bearer $NOETIVE_KEY_SECRET" -H "Content-Type: application/json" -d '{"namespace":"global","model":"Qwen3-Embedding-4B","dimensions":1024,"items":[{"text":"Checkout is failing again, the card processor is not responding."}]}'
    ```

    A frame appears on the open stream:

    ```text theme={null}
    event: match
    data: {"message_id":"msg_01je9c40f1b2c4937a2","seq":150,"score":0.61}
    ```

    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](/semantik/delivery) for what else a subscriber has to handle.
  </Step>
</Steps>

## What you just used

| You did                                 | Endpoint                            |
| --------------------------------------- | ----------------------------------- |
| Sent a message into a namespace         | `POST /v1/publish`                  |
| Asked what already matches a meaning    | `POST /v1/search`                   |
| Asked to be told when something matches | `POST /v1/subscribe`                |
| Checked a query before running it       | `POST /v1/lint` (no API key needed) |

## Next

<CardGroup cols={2}>
  <Card title="Which capability for which problem" icon="signs-post" href="/semantik/search-or-subscribe">
    Search or subscribe, and which SemQL clause fits.
  </Card>

  <Card title="SemQL" icon="code" href="/semantik/query-language">
    DISTANCE, DIRECTION, CONTRAST and the scoping clauses.
  </Card>

  <Card title="From your editor" icon="terminal" href="/guides/mcp-setup">
    Use Semantik from Cursor, Claude Code and other MCP clients.
  </Card>

  <Card title="Namespaces" icon="box" href="/semantik/namespaces">
    Isolation, embedding models, and the shared global namespace.
  </Card>

  <Card title="Errors and retries" icon="triangle-alert" href="/semantik/errors">
    The error envelope, which codes to retry, and how to correlate a failure.
  </Card>

  <Card title="Delivery and idempotency" icon="shield-check" href="/semantik/delivery">
    What an acknowledgement promises, and what a subscriber has to handle.
  </Card>
</CardGroup>

Request and response schemas for all five endpoints are under **Semantik API** in the top navigation.