docs: add api reference guide

docs/docs/reference.md

@@ -0,0 +1,46 @@
+# API Reference
+
+Phantasm offers a simple gRPC API for the client to interact with the server,
+specifically the _Receiver Server_. There is only one core API method that you
+need to understand and that is the get approval method.
+
+## GetApproval
+
+This is the core method that you will integrate into your AI agent to obtain
+approval from the approvers before executing a tool. This is a blocking call, so
+if possible, you may want to run it in a separate thread or process.
+
+One of Phantasm's most distinctive features is its ability to pass parameters
+back and forth. This allows the approvers to review the parameters that the AI
+agent intends to use and either approve or deny the request based on them. The
+approvers can also modify the parameters before granting approval.
+
+Ideally, the AI agent should use the parameters returned by the approvers as the
+final parameters for executing the tool, rather than the original parameters.
+This ensures that the AI agent executes the tool accurately.
+
+### Request
+
+```proto
+message GetApprovalRequest {
+    string name = 1;
+    string parameters = 2;
+    string context = 3;
+}
+```
+
+- name: Name of the function the AI agent wants to execute.
+- parameters: Parameters to pass to the function.
+- context: Additional context to pass to the approvers.
+
+### Response
+
+```proto
+message GetApprovalResponse {
+    bool approved = 1;
+    string parameters = 2;
+}
+```
+
+- approved: Boolean indicating if the request was approved.
+- parameters: Parameters to pass to the function if approved.

docs/index.md

@@ -20,18 +20,19 @@ Phantasm consists of 3 main components: Client, Server, and Dashboard.
 
 ### Server
 
-The Server is the primary component that connects the Client and the Dashboard.
+The server is the primary component that connects the client and the dashboard.
 The server responsible for receiving the approval requests from the client is
 called the _Receiver Server_ and the server responsible for coordinating the
 approval requests with the dashboard is called the _Coordinator Server_.
 
-The _Receiver Server_ uses gRPC while the _Coordinator Server_ uses WebSocket.
-Both servers are written in Rust and are controlled by Phantasm's CLI. If you're
-using Docker, this CLI is already the primary entry point for the image.
+The _Receiver Server_ uses gRPC while the _Coordinator Server_ uses WebSocket
+protocol. Both servers are written in Rust and are controlled by Phantasm's CLI.
+If you're using Docker, this CLI is already the primary entry point for the
+image.
 
 ### Client
 
-The Client is a language-specific library that you can use to connect your AI
+The client is a language-specific library that you can use to connect your AI
 agent to the _Receiver Server_. The core concept of the client is to send an
 approval request to the server before your AI agent executes a certain function
 and waits for approval from the approvers.

mkdocs.yml

@@ -53,6 +53,7 @@ extra_css:
 nav:
   - Documentation:
       - Introduction: index.md
+      - API Reference: docs/reference.md
 
 markdown_extensions:
   - admonition