THE NATIVE CONTRACT

API Reference.

Server banner masidyn/1.2. Base URL http://127.0.0.1:11434. The full machine-readable spec is published as openapi.yaml ↗.

ENDPOINTS

Five routes, one dialect.

Responses are bound to the process with X-Masidyn-Instance-Id and X-Masidyn-Boot-Id headers. The tool envelope is masidyn-tool-envelope v1.

GET

/health

Liveness + native readiness

Returns product, status, and native_ready. No auth. Safe to poll.

GET

/v1/identity

Bound runtime identity

The exact instance_id, boot_id, source SHA-256, and backend binary SHA-256 the process is bound to. Launchers verify MasiDyn with this.

GET

/v1/models

Installed model list

Standard list shape { object: 'list', data: [{ id, object, owned_by }] }.

POST

/v1/chat/completions

Chat / completion (native dialect)

Standard chat-completions request. Supports stream, temperature, num_predict, num_ctx, and the masidyn-tool-envelope. Streams as SSE chat.completion.chunk events.

POST

/v1/embeddings

Text embeddings

768-dim vectors from the native nomic-embed helper (feature-hash fallback when MASIDYN_ALLOW_HASH_EMBEDDINGS=1).

POST /v1/chat/completions

Standard chat-completions request shape. Client knobs map to native backend options: temperature, num_predict / max_tokens, and num_ctx. Set stream: true for SSE.

requestapplication/json

{
  "model": "masidyn-word:latest",
  "messages": [
    { "role": "system", "content": "You are helpful." },
    { "role": "user", "content": "Explain GGUF in one line." }
  ],
  "temperature": 0.2,
  "max_tokens": 256,
  "stream": false
}

response · 200chat.completion

{
  "id": "chatcmpl-masidyn-1737331200",
  "object": "chat.completion",
  "created": 1737331200,
  "model": "masidyn-word:latest",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "..." },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0 }
}

response · streamtext/event-stream

data: {"id":"chatcmpl-masidyn-...","object":"chat.completion.chunk",
       "choices":[{"index":0,"delta":{"content":"GG"},"finish_reason":null}]}
data: {"...":"...","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]

POST /v1/embeddings

Accepts a string or array of strings. Returns 768-dim vectors from the native nomic-embed-text helper. The X-Masidyn-Embed-Backend header reports native or the feature-hash fallback.

requestapplication/json

{
  "model": "nomic-embed-text",
  "input": ["sovereign intelligence", "local by design"]
}

response · 200list

{
  "object": "list",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [/* 768 floats */] },
    { "object": "embedding", "index": 1, "embedding": [/* 768 floats */] }
  ],
  "model": "nomic-embed-text",
  "usage": { "prompt_tokens": 0, "total_tokens": 0 }
}

GET /v1/identity

The verifiable identity contract. native_ready is true only when a backend binary is bound and hashable.

response · 200masidyn.identity

{
  "object": "masidyn.identity",
  "product": "masidyn",
  "version": "0.masidyn-1.3",
  "instance_id": "...",
  "boot_id": "...",
  "server_source_sha256": "...",
  "backend_sha256": "...",
  "native_ready": true,
  "default_model": "masidyn-word:latest",
  "endpoints": {
    "identity": "/v1/identity",
    "models": "/v1/models",
    "chat_completions": "/v1/chat/completions",
    "completions": "/v1/completions",
    "embeddings": "/v1/embeddings"
  },
  "tool_protocol": { "name": "masidyn-tool-envelope", "version": 1 }
}