Publish a message

curl --request POST \
  --url https://semantik.noetive.io/v1/publish \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "namespace": "global",
  "model": "Qwen3-Embedding-4B",
  "dimensions": 1024,
  "items": [
    {
      "text": "Transformer models have reshaped NLP benchmarks."
    }
  ],
  "metadata": {
    "source": "arxiv",
    "author": "jdoe"
  },
  "ack": "durable"
}
'

{
  "message_id": "<string>",
  "epoch": 123,
  "seq": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

POST

publish

curl --request POST \
  --url https://semantik.noetive.io/v1/publish \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "namespace": "global",
  "model": "Qwen3-Embedding-4B",
  "dimensions": 1024,
  "items": [
    {
      "text": "Transformer models have reshaped NLP benchmarks."
    }
  ],
  "metadata": {
    "source": "arxiv",
    "author": "jdoe"
  },
  "ack": "durable"
}
'

{
  "message_id": "<string>",
  "epoch": 123,
  "seq": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "request_id": "<string>",
  "retry_after_ms": 123
}

Authorizations

Authorization

string

header

required

API key bearer token. Obtain from the Noetive dashboard. Pass as: Authorization: Bearer <api-key>.

Body

application/json

namespace

string

required

Target namespace alias — a registered name (e.g. articles) or the well-known global alias. Required; there is no default. Every request is validated against the namespace's configured model and dimensions; a mismatch returns 400 invalid_request.

Pass the alias, not the ns_... identifier shown in the dashboard — a raw identifier is rejected with 400 invalid_request.

Maximum string length: 64

Pattern: ^[A-Za-z0-9_-]+$

model

string

required

Embedding model name. Required; there is no default. Must match the model configured on the namespace, or the request fails with 400 model_not_provisioned.

dimensions

integer

required

Embedding vector dimensionality. Required; there is no default. Must match the dimensionality configured on the namespace for model, or the request fails with 400 model_not_provisioned.

Required range: 1 <= x <= 4096

items

object[]

required

Messages to publish. Currently exactly one item per request. Each item is either a text message (server computes the embedding) or a pre-computed embedding vector.

Required array length: 1 element

Show child attributes

metadata

object

Optional key-value metadata attached to the message.

Every limit is measured in UTF-8 bytes, not characters: max 16 keys; max 64 bytes per key; max 256 bytes per value; max 4 KB summed across all keys and values.

Keys and values must be valid UTF-8 and must not contain ASCII control characters. Metadata is echoed back in search results, so a raw newline or escape byte is refused rather than propagated.

Show child attributes

idempotency_key

string

Optional client-supplied key that makes a publish safe to retry. Must be valid UTF-8 and free of control characters.

Re-sending the same key with the same message within 5 minutes returns the original message_id and seq without storing a second copy. The key is scoped to the namespace, so a retry is still recognised even if its embedding differs slightly from the first attempt.

Re-using a live key for a different message returns 409 idempotency_key_conflict. Two different messages cannot share one identity, and the second is not stored.

The retry window is best-effort and does not survive a server restart: a retry sent across one may be stored a second time. Use it to make a retry safe, not as a long-lived deduplication guarantee.

Maximum string length: 256

ack

enum<string>

Acknowledgement durability. Defaults to stored when omitted.

stored — returns once the message is on durable media.
durable — returns once the message is on durable media.

Both modes currently give the same guarantee: a publish is acknowledged only after the message is written to durable storage, and an acknowledged message survives a server restart. The field is accepted so a future deployment can offer a weaker, faster mode without a breaking change; today, choosing between them changes nothing.

Available options:

stored,

durable

Response

Message acknowledged.

message_id

string

required

Stable, globally unique identifier of the published message. The same message_id appears in ResultItem.message_id when this message matches a future search.

epoch

integer<uint64>

required

Opaque token accompanying seq. Treat it as opaque: do not order by it, compare it across namespaces, or derive meaning from its value. It is returned so a future deployment can qualify seq without a breaking change.

seq

integer<uint64>

required

Opaque write-position token, paired with epoch.

It is not a namespace-wide ordering. Consecutive publishes to one namespace routinely return unrelated and non-increasing values, so seq must not be used to order a namespace's messages, to detect gaps, or as a cursor — it is not a position usable with /v1/search. Use message_id to identify a message and publish-time metadata to order one.