update quickstart

1 files changed, 183 insertions, 0 deletions

diff --git a/apps/docs/user-profiles/api.mdx b/apps/docs/user-profiles/api.mdx
new file mode 100644
index 00000000..73135aa6
--- /dev/null
+++ b/apps/docs/user-profiles/api.mdx
@@ -0,0 +1,183 @@
+---
+title: "Profile API"
+description: "Endpoint details and response structure for user profiles"
+sidebarTitle: "API Reference"
+icon: "code"
+---
+
+## Endpoint
+
+**`POST /v4/profile`**
+
+Retrieves a user's profile, optionally combined with search results.
+
+## Request
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | Yes | Bearer token with your API key |
+| `Content-Type` | Yes | `application/json` |
+
+### Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerTag` | string | Yes | The container tag (usually user ID) to get profiles for |
+| `q` | string | No | Optional search query to include search results with the profile |
+
+## Response
+
+```json
+{
+  "profile": {
+    "static": [
+      "User is a software engineer",
+      "User specializes in Python and React",
+      "User prefers dark mode interfaces"
+    ],
+    "dynamic": [
+      "User is working on Project Alpha",
+      "User recently started learning Rust",
+      "User is debugging authentication issues"
+    ]
+  },
+  "searchResults": {
+    "results": [...],  // Only if 'q' parameter was provided
+    "total": 15,
+    "timing": 45.2
+  }
+}
+```
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `profile.static` | string[] | Long-term, stable facts about the user |
+| `profile.dynamic` | string[] | Recent context and temporary information |
+| `searchResults` | object | Only present if `q` parameter was provided |
+| `searchResults.results` | array | Matching memory results |
+| `searchResults.total` | number | Total number of matches |
+| `searchResults.timing` | number | Query execution time in milliseconds |
+
+## Basic Request
+
+<CodeGroup>
+
+```typescript TypeScript
+const response = await fetch('https://api.supermemory.ai/v4/profile', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    containerTag: 'user_123'
+  })
+});
+
+const data = await response.json();
+
+console.log("Static facts:", data.profile.static);
+console.log("Dynamic context:", data.profile.dynamic);
+```
+
+```python Python
+import requests
+import os
+
+response = requests.post(
+    'https://api.supermemory.ai/v4/profile',
+    headers={
+        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'containerTag': 'user_123'
+    }
+)
+
+data = response.json()
+
+print("Static facts:", data['profile']['static'])
+print("Dynamic context:", data['profile']['dynamic'])
+```
+
+```bash cURL
+curl -X POST https://api.supermemory.ai/v4/profile \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "containerTag": "user_123"
+  }'
+```
+
+</CodeGroup>
+
+## Profile with Search
+
+Include a search query to get both profile data and relevant memories in one call:
+
+<CodeGroup>
+
+```typescript TypeScript
+const response = await fetch('https://api.supermemory.ai/v4/profile', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    containerTag: 'user_123',
+    q: 'deployment errors yesterday'
+  })
+});
+
+const data = await response.json();
+
+// Profile data
+const profile = data.profile;
+
+// Search results (only present because we passed 'q')
+const searchResults = data.searchResults?.results || [];
+```
+
+```python Python
+response = requests.post(
+    'https://api.supermemory.ai/v4/profile',
+    headers={
+        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'containerTag': 'user_123',
+        'q': 'deployment errors yesterday'
+    }
+)
+
+data = response.json()
+
+profile = data['profile']
+search_results = data.get('searchResults', {}).get('results', [])
+```
+
+</CodeGroup>
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| `400` | Missing or invalid `containerTag` |
+| `401` | Invalid or missing API key |
+| `404` | Container not found |
+| `500` | Internal server error |
+
+## Rate Limits
+
+Profile requests count toward your standard API rate limits. Since profiles are cached, repeated requests for the same user are efficient.
+
+<Card title="See Examples" icon="laptop-code" href="/user-profiles/examples">
+  View complete integration examples for chat apps, support systems, and more
+</Card>