Revise API Documentation for Improved Clarity and Consistency (#546)

* docs: make versionUUid required for API * docs: removed duplicate * docs: removed auth header Auth Headers already documented on the top of the Document * docs: fixxed style * docs: fixxed response * docs: removed example nowhere else is a example, so why there? * docs: added log endpoint git messed stuff up * docs: added link to vercels docs for body formating
latitude-dev · Nov 5, 2024 · 388e4a4 · 388e4a4
1 parent d154570
commit 388e4a4
Showing 1 changed file with 66 additions and 72 deletions.
diff --git a/docs/guides/prompt-manager/api-access.mdx b/docs/guides/prompt-manager/api-access.mdx
@@ -61,7 +61,7 @@ Run a specific document (prompt) with optional parameters.
 **Path Parameters:**
 
 - `projectId`: Your project ID (required)
-- `versionUuid`: Version UUID (optional, defaults to 'live')
+- `versionUuid`: Version UUID (required, optional for SDK's defaults to 'live')
 
 **Request Body:**
 
@@ -151,12 +151,17 @@ The previously described `POST /projects/{projectId}/versions/{versionUuid}/docu
 
 **Request Body:**
 
+- follows OpenAI's format or the [vercel's ai sdk](https://sdk.vercel.ai/docs/reference/ai-sdk-core/stream-text#api-signature)
+
 ```json
 {
   "messages": [
     {
       "role": "user" | "system" | "assistant",
-      "content": string
+        {
+          "type": "text",
+          "content": string
+        }
     }
   ]
 }
@@ -165,47 +170,6 @@ The previously described `POST /projects/{projectId}/versions/{versionUuid}/docu
 **Response:**
 The response is a stream of Server-Sent Events (SSE), similar to the "Run a Document" endpoint.
 
-#### 3. Get a Prompt
-
-Retrieve a specific prompt by its path.
-
-**Endpoint:** `GET /projects/{projectId}/versions/{versionUuid}/documents/{documentPath}`
-
-**Path Parameters:**
-
-- `projectId`: Your project ID (required)
-- `versionUuid`: Version UUID (optional, defaults to 'live')
-- `documentPath`: Path to the document (required)
-
-**Request Headers:**
-
-Include your API key in the `Authorization` header of your HTTP requests:
-
-```
-Authorization: Bearer YOUR_API_KEY
-```
-
-**Response:**
-
-The response contains the document details along with its configuration.
-
-**Response Body:**
-
-```json
-{
-  "id": "document-id",
-  "name": "Document Name",
-  "content": "Document content",
-  "path": "path/to/document",
-  "resolvedContent": "Compiled document content (might be nil)",
-  "contentHash": "Document content hash (might be nil)",
-  "commitId": "Commit ID",
-  "deletedAt": "Deleted at timestamp (might be nil)",
-  "createdAt": "Created at timestamp",
-  "updatedAt": "Updated at timestamp",
-  "config": "Document frontmatter configuration (might be nil)",
-}
-
 ### Handling Server-Sent Events (SSE)
 
 The API uses SSE for real-time updates. Here's how to handle SSE responses:
@@ -228,7 +192,7 @@ The API uses standard HTTP status codes. In case of an error, the response body
 }
 ```
 
-3. #### Get a Document
+#### 3. Get a Document
 
 Retrieve a specific prompt by its path.
 
@@ -237,17 +201,9 @@ Retrieve a specific prompt by its path.
 **Path Parameters:**
 
 - `projectId`: Your project ID (required)
-- `versionUuid`: Version UUID (optional, defaults to 'live')
+- `versionUuid`: Version UUID (required, optional for SDK's defaults to 'live')
 - `path`: Path to the document (required)
 
-**Request Headers:**
-
-Include your API key in the `Authorization` header of your HTTP requests:
-
-```
-Authorization: Bearer YOUR_API_KEY
-```
-
 **Response:**
 
 The response contains the document details along with its configuration.
@@ -257,58 +213,96 @@ The response contains the document details along with its configuration.
 ```json
 {
   "id": "document-id",
-  "name": "Document Name",
+  "documentUuid": "document-uuid",
+  "path": "path/to/document",
   "content": "Document content",
+  "resolvedContent": "Document content without comments",
+  "contentHash": "content-hash",
+  "commitId": "commit-id",
+  "deletedAt": "deleted-at",
+  "createdAt": "created-at",
+  "updatedAt": "updated-at",
+  "mergedAt": "merged-at",
+  "projectId": "project-id",
   "config": {
     "provider": "Provider name",
     "model": "Model name"
   }
 }
 ```
 
-**Example Request:**
+#### 4. Evaluate a Conversation
+
+Evaluate a conversation using configured evaluations.
+
+**Endpoint:** `POST /conversations/{conversationUuid}/evaluate`
+
+**Path Parameters:**
+
+- `conversationUuid`: UUID of the conversation to evaluate
+
+**Request Body:**
 
-```bash
-curl -X GET "https://gateway.latitude.so/api/v2/projects/123/versions/live/documents/path/to/document" \
-     -H "Authorization: Bearer YOUR_API_KEY"
+```json
+{
+  "evaluationUuids": ["evaluation-uuid-1", "evaluation-uuid-2"] // optional, defaults to all evaluations connected to the conversation prompt
+}
 ```
 
-**Example Response:**
+**Response:**
 
 ```json
 {
-  "id": "document-id",
-  "name": "Document Name",
-  "content": "Document content",
-  "config": {
-    "provider": "Provider name",
-    "model": "Model name"
-  }
+  "evaluations": ["evaluation-uuid-1", "evaluation-uuid-2"] // array of evaluation UUIDs that will be run
 }
 ```
 
-#### 4. Evaluate a Conversation
+#### 5. Create Log Entry
 
-Evaluate a conversation using configured evaluations.
+Create a log entry for a document.
 
-**Endpoint:** `POST /conversations/{conversationUuid}/evaluate`
+**Endpoint:** `POST /projects/{projectId}/versions/{versionUuid}/documents/logs`
 
 **Path Parameters:**
 
-- `conversationUuid`: UUID of the conversation to evaluate
+- `projectId`: Your project ID (required)
+- `versionUuid`: Version UUID (required, optional for SDK's defaults to 'live')
 
 **Request Body:**
 
+- follows OpenAI's format or the [vercel's ai sdk](https://sdk.vercel.ai/docs/reference/ai-sdk-core/stream-text#api-signature)
+
 ```json
 {
-  "evaluationUuids": ["evaluation-uuid-1", "evaluation-uuid-2"] // optional, defaults to all evaluations connected to the conversation prompt
+  "path": "path/to/document",
+  "messages": [
+    {
+      "role": "user" | "system" | "assistant",
+        {
+          "type": "text",
+          "content": string
+        }
+    }
+  ],
+  "response": string
 }
 ```
 
 **Response:**
 
 ```json
 {
-  "evaluations": ["evaluation-uuid-1", "evaluation-uuid-2"] // array of evaluation UUIDs that will be run
+  "id": "document-id",
+  "uuid": "log-uuid",
+  "documentUuid": "document-uuid",
+  "commitId": "commit-id",
+  "resolvedContent": "Document content without comments",
+  "contentHash": "content-hash",
+  "parameters": {},
+  "customIdentifier": "custom-identifier",
+  "duration": "duration",
+  "source": "source",
+  "createdAt": "created-at",
+  "updatedAt": "updated-at",
 }
 ```