From 3e98d13f6b341e7a6e981121fa6fa9b7e1c29966 Mon Sep 17 00:00:00 2001
From: KernelDeimos <eric.alex.dube@gmail.com>
Date: Mon, 7 Apr 2025 14:37:45 -0400
Subject: [PATCH] doc: document driver endpoint

---
 doc/api/drivers.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 doc/api/drivers.md

diff --git a/doc/api/drivers.md b/doc/api/drivers.md
new file mode 100644
index 00000000..f38c656e
--- /dev/null
+++ b/doc/api/drivers.md
@@ -0,0 +1,60 @@
+## Puter Drivers
+
+### **POST** `/drivers/call`
+
+#### Notes
+
+- **HTTP response status** -
+  A successful driver response, even if the response is an error message, will always have HTTP status `200`. Note that sometimes this will include rate limit and usage limit errors as well.
+
+This endpoint allows you to call a Puter driver. Whether or not the
+driver call fails, this endpoint will respond with HTTP 200 OK.
+When a driver call fails, you will get a JSON response from the driver
+with 
+
+#### Parameters
+
+Parameters are provided in the request body. The content type of the
+request should be `application/json`.
+
+- **interface:** `string`
+  - **description:** The type of driver to call. For example,
+    LLMs use the interface called `puter-chat-completion`.
+- **service:** `string`
+  - **description:** The name of the service to use. For example, the `claude` service might be used for `puter-chat-completion`.
+- **method:** `string`
+  - **description:** The name of the method to call. For example, LLMs implement `complete` which does a chat completion, and `list` which lists models.
+- **args:** `object`
+  - **description:** Parametized arguments for the driver call. For example, `puter-chat-completion`'s `complete` method supports the arguments `messages` and `temperature` (and others), so you might set this to `{ "messages": [...], "temperature": 1.2 }`
+
+#### Example
+```json
+{
+    "interface": "<name of interface>",
+    "service": "<name of service>",
+    "method": "<name of method>",
+    "args": { "parametized": "arguments" }
+}
+```
+
+#### Response
+
+- **Error Response** - Driver error responses will always have **status 200**, content type `application/json`, and a response body in this format:
+  ```json
+  {
+    "success": false,
+    "error": {
+        "code": "string identifier for the error",
+        "message": "some message about the error",
+    }
+  }
+  ```
+- **Success Response** - The success response is either a JSON response
+  wrapped in `{ "success": true, "result": ___ }`, or a response with a
+  `Content-Type` that is **not** `application/json`.
+  ```json
+  {
+    "success": true,
+    "result": {}
+  }
+  ```
\ No newline at end of file