Merge pull request #956 from jmorganca/mattw/apidocupdate

docs/api.md

@@ -45,7 +45,7 @@ Advanced parameters (optional):
 - `system`: system prompt to (overrides what is defined in the `Modelfile`)
 - `template`: the full prompt or prompt template (overrides what is defined in the `Modelfile`)
 - `context`: the context parameter returned from a previous request to `/generate`, this can be used to keep a short conversational memory
-- `stream`: if `false` the response will be be returned as a single response object, rather than a stream of objects
+- `stream`: if `false` the response will be returned as a single response object, rather than a stream of objects
 
 ### Request
 
@@ -58,7 +58,7 @@ curl -X POST http://localhost:11434/api/generate -d '{
 
 ### Response
 
-A stream of JSON objects:
+If `stream` is not specified, or set to `true`, a stream of JSON objects is returned:
 
 ```json
 {
@@ -102,6 +102,26 @@ To calculate how fast the response is generated in tokens per second (token/s),
 }
 ```
 
+If `stream` is set to `false`, the response will be a single JSON object:
+
+```json
+{
+  "model": "llama2:7b",
+  "created_at": "2023-08-04T19:22:45.499127Z",
+  "response": "The sky is blue because it is the color of the sky.",
+  "context": [1, 2, 3],
+  "done": true,
+  "total_duration": 5589157167,
+  "load_duration": 3013701500,
+  "sample_count": 114,
+  "sample_duration": 81442000,
+  "prompt_eval_count": 46,
+  "prompt_eval_duration": 1160282000,
+  "eval_count": 13,
+  "eval_duration": 1325948000
+}
+```
+
 ## Create a Model
 
 ```shell
@@ -114,7 +134,7 @@ Create a model from a [`Modelfile`](./modelfile.md)
 
 - `name`: name of the model to create
 - `path`: path to the Modelfile
-- `stream`: (optional) if `false` the response will be be returned as a single response object, rather than a stream of objects
+- `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects
 
 ### Request
 
@@ -151,6 +171,8 @@ curl http://localhost:11434/api/tags
 
 ### Response
 
+A single JSON object will be returned.
+
 ```json
 {
   "models": [
@@ -216,6 +238,10 @@ curl http://localhost:11434/api/copy -d '{
 }'
 ```
 
+### Response
+
+The only response is a 200 OK if successful.
+
 ## Delete a Model
 
 ```shell
@@ -226,7 +252,7 @@ Delete a model and its data.
 
 ### Parameters
 
-- `model`: model name to delete
+- `name`: model name to delete
 
 ### Request
 
@@ -236,6 +262,10 @@ curl -X DELETE http://localhost:11434/api/delete -d '{
 }'
 ```
 
+### Response
+
+If successful, the only response is a 200 OK.
+
 ## Pull a Model
 
 ```shell
@@ -248,7 +278,7 @@ Download a model from the ollama library. Cancelled pulls are resumed from where
 
 - `name`: name of the model to pull
 - `insecure`: (optional) allow insecure connections to the library. Only use this if you are pulling from your own library during development.
-- `stream`: (optional) if `false` the response will be be returned as a single response object, rather than a stream of objects
+- `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects
 
 ### Request
 
@@ -260,11 +290,49 @@ curl -X POST http://localhost:11434/api/pull -d '{
 
 ### Response
 
+If `stream` is not specified, or set to `true`, a stream of JSON objects is returned:
+
+The first object is the manifest:
+
+```json
+{
+  "status": "pulling manifest"
+}
+```
+
+Then there is a series of downloading responses. Until any of the download is completed, the `completed` key may not be included. The number of files to be downloaded depends on the number of layers specified in the manifest.
+
 ```json
 {
   "status": "downloading digestname",
   "digest": "digestname",
-  "total": 2142590208
+  "total": 2142590208, 
+  "completed": 241970
+}
+```
+
+After all the files are downloaded, the final responses are:
+
+```json
+{
+    "status": "verifying sha256 digest"
+}
+{
+    "status": "writing manifest"
+}
+{
+    "status": "removing any unused layers"
+}
+{
+    "status": "success"
+}
+```
+
+if `stream` is set to false, then the response is a single JSON object:
+
+```json
+{
+  "status": "success"
 }
 ```
 
@@ -280,7 +348,7 @@ Upload a model to a model library. Requires registering for ollama.ai and adding
 
 - `name`: name of the model to push in the form of `<namespace>/<model>:<tag>`
 - `insecure`: (optional) allow insecure connections to the library. Only use this if you are pushing to your library during development.
-- `stream`: (optional) if `false` the response will be be returned as a single response object, rather than a stream of objects
+- `stream`: (optional) if `false` the response will be returned as a single response object, rather than a stream of objects
 
 ### Request
 
@@ -292,7 +360,7 @@ curl -X POST http://localhost:11434/api/push -d '{
 
 ### Response
 
-Streaming response that starts with:
+If `stream` is not specified, or set to `true`, a stream of JSON objects is returned:
 
 ```json
 { "status": "retrieving manifest" }
@@ -325,6 +393,12 @@ Finally, when the upload is complete:
 {"status":"success"}
 ```
 
+If `stream` is set to `false`, then the response is a single JSON object:
+
+```json
+{"status":"success"}
+```
+
 ## Generate Embeddings
 
 ```shell