Skip to main content

API Reference

GoingMerry serves a local HTTP REST API on port 11434 (http://localhost:11434) for programmatically managing models and executing completions.

1. Generate Completion​

Generate a completion response for a given prompt. Response can be streamed or returned as a single JSON object.

  • Endpoint: POST /api/generate
  • Request Parameters:
    • model (string, required): Model tag to execute (e.g. gemma4).
    • prompt (string, required): Input prompt text.
    • stream (boolean, optional): If true, returns a stream of JSON objects. If false, returns a single JSON object (defaults to true).
    • format (string, optional): Set to json for structured JSON output.
    • options (object, optional): Override Modelfile parameters (e.g. {"temperature": 0.5}).

curl Example (Streaming)​

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "Why is the sky blue?"
}'

Response format (Streaming chunks)​

{"model":"gemma4","created_at":"2026-06-05T14:10:00Z","response":"The","done":false}
{"model":"gemma4","created_at":"2026-06-05T14:10:00Z","response":" sky","done":false}
...
{"model":"gemma4","created_at":"2026-06-05T14:10:01Z","response":"...","done":true,"total_duration":9823901}

curl Example (Non-Streaming)​

curl http://localhost:11434/api/generate -d '{
  "model": "gemma4",
  "prompt": "Why is the sky blue?",
  "stream": false
}'

2. Chat Completions​

Generate a response in a multi-turn conversation thread.

  • Endpoint: POST /api/chat
  • Request Parameters:
    • model (string, required): Model tag.
    • messages (array, required): Array of chat message objects:
      • role (string): system, user, or assistant.
      • content (string): Message text.
    • stream (boolean, optional): Stream chunks (defaults to true).

curl Example​

curl http://localhost:11434/api/chat -d '{
  "model": "gemma4",
  "messages": [
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hi! How can I help you?"},
    {"role": "user", "content": "What is 2+2?"}
  ],
  "stream": false
}'

Response Format​

{
  "model": "gemma4",
  "created_at": "2026-06-05T14:10:05Z",
  "message": {
    "role": "assistant",
    "content": "2 + 2 is 4."
  },
  "done": true
}

3. List Local Models​

Retrieve lists of all model configurations stored in the local registry cache.

  • Endpoint: GET /api/tags
  • curl Example:
curl http://localhost:11434/api/tags

Response Format​

{
  "models": [
    {
      "name": "gemma4:latest",
      "model": "gemma4:latest",
      "modified_at": "2026-06-05T12:00:00Z",
      "size": 4720938102,
      "digest": "a8f8c7e9b23bb8f8c7e9b23bb8f8c7e9b23b"
    }
  ]
}

4. Query Loaded Models (ps)​

Inspect which model configurations are currently loaded and active in memory.

  • Endpoint: GET /api/ps
  • curl Example:
curl http://localhost:11434/api/ps

Response Format​

{
  "models": [
    {
      "name": "gemma4:latest",
      "model": "gemma4:latest",
      "size": 4720938102,
      "digest": "a8f8c7e9b23bb8f8c7e9b23bb8f8c7e9b23b",
      "expires_at": "2026-06-05T14:15:00Z",
      "size_vram": 4720938102
    }
  ]
}

5. Generate Vector Embeddings​

Compute high-dimensional vector embeddings for a given input text.

  • Endpoint: POST /api/embeddings
  • Request Parameters:
    • model (string, required): Model tag.
    • prompt (string, required): Text content to vectorize.

curl Example​

curl http://localhost:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "Here is some text to embed"
}'

Response Format​

{
  "embedding": [0.1023901, -0.0498239, 0.9023812, ...]
}

6. Pull Model​

Pull a model configuration from the registry database.

  • Endpoint: POST /api/pull
  • Request Parameters:
    • model (string, required): Model name.
    • stream (boolean, optional): Stream download progress.

7. Push Model​

Push a custom local model to a remote repository boundary.

  • Endpoint: POST /api/push

8. Create Model​

Compile a new model tag from a Modelfile configuration string.

  • Endpoint: POST /api/create
  • Request Parameters:
    • model (string, required): Target model name.
    • modelfile (string, required): Raw text content of the Modelfile.

9. Delete Model​

Purge a model tag and its weights.

  • Endpoint: DELETE /api/delete
  • Request Parameters:
    • model (string, required): Model name to remove.
curl -X DELETE http://localhost:11434/api/delete -d '{"model": "llama4:8b"}'