Models API

This document details the model management endpoints in Ollama Toolkit v0.1.8, providing interfaces for listing, pulling, modifying, and deleting models.

Endpoints Overview

  • GET /api/tags - List available models

  • GET /api/show - Get model information

  • POST /api/pull - Download a model

  • POST /api/push - Upload a model

  • POST /api/create - Create a custom model

  • POST /api/copy - Copy a model

  • DELETE /api/delete - Delete a model

  • GET /api/ps - List running models

Endpoint: /api/tags

List all available models.

Method

GET

Response

{
  "models": [
    {
      "name": "deepseek-r1:1.5b",
      "modified_at": "2025-02-15T21:26:11Z",
      "size": 1610612736,
      "digest": "sha256:a1b2c3...",
      "details": {
        "format": "gguf",
        "family": "deepseek",
        "parameter_size": "1.5B",
        "quantization_level": "Q4_0"
      }
    },
    {
      "name": "qwen2.5:0.5b",
      "modified_at": "2025-02-14T18:42:33Z",
      "size": 536870912,
      "digest": "sha256:d4e5f6..."
    }
  ]
}

Endpoint: /api/show

Retrieve detailed information about a specific model.

Method

GET

Query Parameters

Parameter

Type

Description

Required

name

string

Name of model to retrieve information for

Yes

Response

{
  "name": "deepseek-r1:1.5b",
  "modified_at": "2025-02-15T21:26:11Z",
  "size": 1610612736,
  "digest": "sha256:a1b2c3...",
  "format": "gguf",
  "family": "deepseek",
  "parameter_size": "1.5B",
  "quantization_level": "Q4_0",
  "model_file": "/path/to/model/file.gguf"
}

Endpoint: /api/pull

Pull a model from the Ollama library.

Method

POST

Request Body

Parameter

Type

Description

Required

name

string

Name of model to pull

Yes

stream

boolean

Stream the response (for progress updates)

No

Response (non-streaming)

{
  "status": "success"
}

Response (streaming)

A stream of JSON objects showing download progress:

{"status":"downloading","digest":"sha256:a1b2c3...","total":1610612736,"completed":104857600}
{"status":"downloading","digest":"sha256:a1b2c3...","total":1610612736,"completed":209715200}
// Additional download progress messages would appear here
{"status":"processing","digest":"sha256:a1b2c3..."}
{"status":"success","digest":"sha256:a1b2c3..."}

Endpoint: /api/create

Create a custom model using a Modelfile.

Method

POST

Request Body

Parameter

Type

Description

Required

name

string

Name of the model to create

Yes

modelfile

string

Contents of the Modelfile

Yes

stream

boolean

Stream the response

No

Response (non-streaming)

{
  "status": "success"
}

Response (streaming)

A stream of JSON objects showing progress:

{"status":"processing","digest":"sha256:a1b2c3..."}
{"status":"success","digest":"sha256:a1b2c3..."}

Endpoint: /api/copy

Copy a model to a new name.

Method

POST

Request Body

Parameter

Type

Description

Required

source

string

Source model name

Yes

destination

string

Destination model name

Yes

Response

{
  "status": "success"
}

Endpoint: /api/delete

Delete a model.

Method

DELETE

Request Body

Parameter

Type

Description

Required

model

string

Name of model to delete

Yes

Response

Empty 200 OK response on success

Endpoint: /api/ps

List running models.

Method

GET

Response

{
  "running": [
    {
      "name": "deepseek-r1:1.5b",
      "status": "running",
      "pid": 12345
    }
  ]
}

Endpoint: /api/push

Push a model to a registry.

Method

POST

Request Body

Parameter

Type

Description

Required

name

string

Name of model to push

Yes

stream

boolean

Stream the response

No

Response (non-streaming)

{
  "status": "success"
}

Response (streaming)

A stream of JSON objects showing upload progress:

{"status":"pushing","digest":"sha256:a1b2c3...","total":1610612736,"completed":104857600}
{"status":"pushing","digest":"sha256:a1b2c3...","total":1610612736,"completed":209715200}
// Additional upload progress messages would appear here
{"status":"success","digest":"sha256:a1b2c3..."}

Mathematical Precision

The Models API follows Eidosian principles of structural control, ensuring each operation is mathematically precise and recursively consistent:

  • Model Hierarchy: Each model exists within a mathematically defined space

  • Operation Atomicity: All operations (pull, copy, delete) are atomic

  • Idempotent Actions: Repeated operations yield consistent results

  • Structural Integrity: Model relationships maintain referential integrity

  • Recursive Discoverability: Model information reveals its own structure

Client Implementation

The Ollama Toolkit client implements these endpoints with both synchronous and asynchronous interfaces, maintaining structural integrity across the API surface.