diff --git a/api-reference/openapi/sessions.json b/api-reference/openapi/sessions.json
new file mode 100644
index 0000000..3f5689f
--- /dev/null
+++ b/api-reference/openapi/sessions.json
@@ -0,0 +1,407 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Recoup API - Sessions",
+    "description": "Sessions — sandboxed runs of an LLM-driven agent with tool use, lifecycle hooks, and persistence. Each session pairs one Vercel Sandbox with one or more chat threads.",
+    "license": {
+      "name": "MIT"
+    },
+    "version": "1.0.0"
+  },
+  "servers": [
+    {
+      "url": "https://api.recoupable.com"
+    }
+  ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    },
+    {
+      "BearerAuth": []
+    }
+  ],
+  "paths": {
+    "/api/sessions": {
+      "post": {
+        "summary": "Create session",
+        "description": "Creates a new agent session and an initial empty chat in a single transaction. The session is created in the `provisioning` lifecycle state — a separate orchestration step claims it and starts the sandbox.",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/CreateSessionRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Session and initial chat created successfully.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateSessionResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request body — either malformed JSON or a field failed validation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthorized — invalid or missing API key / Bearer token.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "Server error — the session could not be persisted.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuth": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-api-key"
+      },
+      "BearerAuth": {
+        "type": "http",
+        "scheme": "bearer"
+      }
+    },
+    "schemas": {
+      "CreateSessionRequest": {
+        "type": "object",
+        "description": "All fields are optional. An empty body is valid and creates a session with default settings.",
+        "properties": {
+          "title": {
+            "type": "string",
+            "description": "Display title for the session. When omitted, the server generates one."
+          },
+          "repoOwner": {
+            "type": "string",
+            "description": "GitHub repository owner (user or org). Validated against GitHub's owner-name rules."
+          },
+          "repoName": {
+            "type": "string",
+            "description": "GitHub repository name. Validated against GitHub's repo-name rules."
+          },
+          "branch": {
+            "type": "string",
+            "description": "Branch the session should check out. Ignored when `isNewBranch` is true — the server generates a new branch name in that case."
+          },
+          "cloneUrl": {
+            "type": "string",
+            "description": "Clone URL the sandbox should fetch from."
+          },
+          "isNewBranch": {
+            "type": "boolean",
+            "description": "When true, the server generates a fresh branch name (e.g. `xx/abcdef12`) instead of using `branch`."
+          },
+          "sandboxType": {
+            "type": "string",
+            "enum": [
+              "vercel"
+            ],
+            "description": "Which sandbox provider to use. Currently only `vercel` is accepted."
+          },
+          "autoCommitPush": {
+            "type": "boolean",
+            "description": "Per-session override for automatic commit + push. When omitted, the account's default preference applies."
+          },
+          "autoCreatePr": {
+            "type": "boolean",
+            "description": "Per-session override for opening a PR after auto-commit. Only meaningful when `autoCommitPush` is true. When omitted, the account's default preference applies."
+          }
+        }
+      },
+      "CreateSessionResponse": {
+        "type": "object",
+        "required": [
+          "session",
+          "chat"
+        ],
+        "properties": {
+          "session": {
+            "$ref": "#/components/schemas/Session"
+          },
+          "chat": {
+            "$ref": "#/components/schemas/Chat"
+          }
+        }
+      },
+      "Chat": {
+        "type": "object",
+        "required": [
+          "id",
+          "sessionId",
+          "title",
+          "modelId",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Chat id (nanoid)."
+          },
+          "sessionId": {
+            "type": "string",
+            "description": "Owning session id."
+          },
+          "title": {
+            "type": "string",
+            "description": "Display title for the chat. The initial chat created with a session is titled `New chat`."
+          },
+          "modelId": {
+            "type": "string",
+            "description": "AI Gateway model identifier the chat is configured to use (e.g. `openai/gpt-5.4`)."
+          },
+          "activeStreamId": {
+            "type": "string",
+            "nullable": true,
+            "description": "Id of an in-flight assistant stream, if one is active."
+          },
+          "lastAssistantMessageAt": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "Timestamp of the most recent assistant message in this chat."
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "Session": {
+        "type": "object",
+        "required": [
+          "id",
+          "userId",
+          "title",
+          "status",
+          "isNewBranch",
+          "globalSkillRefs",
+          "lifecycleVersion",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Session id (nanoid)."
+          },
+          "userId": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Owning account id. Named `userId` here for compatibility with existing clients; on the server side this is the account_id foreign key into the accounts table."
+          },
+          "title": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "running",
+              "completed",
+              "failed",
+              "archived"
+            ]
+          },
+          "repoOwner": {
+            "type": "string",
+            "nullable": true,
+            "description": "GitHub repo owner if the session is bound to a repository."
+          },
+          "repoName": {
+            "type": "string",
+            "nullable": true
+          },
+          "branch": {
+            "type": "string",
+            "nullable": true
+          },
+          "cloneUrl": {
+            "type": "string",
+            "nullable": true,
+            "description": "Clone URL the sandbox should fetch from."
+          },
+          "isNewBranch": {
+            "type": "boolean",
+            "description": "True when this session created and pushed a new branch (not committing back to the original)."
+          },
+          "autoCommitPushOverride": {
+            "type": "boolean",
+            "nullable": true,
+            "description": "Per-session override for auto commit + push behavior. `null` means use the account's default preference."
+          },
+          "autoCreatePrOverride": {
+            "type": "boolean",
+            "nullable": true,
+            "description": "Per-session override for creating a PR after auto-commit. `null` means use the account's default preference."
+          },
+          "globalSkillRefs": {
+            "type": "array",
+            "description": "Skills attached to the agent at provision time.",
+            "items": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          },
+          "sandboxState": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": true,
+            "description": "Sandbox runtime state (Vercel Sandbox)."
+          },
+          "lifecycleState": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "provisioning",
+              "active",
+              "hibernating",
+              "hibernated",
+              "restoring",
+              "archived",
+              "failed"
+            ],
+            "description": "Lifecycle orchestration state for the sandbox."
+          },
+          "lifecycleVersion": {
+            "type": "integer",
+            "description": "Optimistic concurrency token for lifecycle transitions."
+          },
+          "lastActivityAt": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "sandboxExpiresAt": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "hibernateAfter": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "lifecycleRunId": {
+            "type": "string",
+            "nullable": true
+          },
+          "lifecycleError": {
+            "type": "string",
+            "nullable": true
+          },
+          "linesAdded": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Lines added across the session's diff. Defaults to 0; null when stats have not been computed."
+          },
+          "linesRemoved": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Lines removed across the session's diff. Defaults to 0; null when stats have not been computed."
+          },
+          "prNumber": {
+            "type": "integer",
+            "nullable": true,
+            "description": "GitHub pull request number, set after the session has opened a PR."
+          },
+          "prStatus": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "open",
+              "merged",
+              "closed"
+            ],
+            "description": "Lifecycle of the linked pull request."
+          },
+          "snapshotUrl": {
+            "type": "string",
+            "nullable": true
+          },
+          "snapshotCreatedAt": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "snapshotSizeBytes": {
+            "type": "integer",
+            "nullable": true
+          },
+          "cachedDiff": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": true
+          },
+          "cachedDiffUpdatedAt": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "createdAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updatedAt": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "Error": {
+        "type": "object",
+        "required": [
+          "status",
+          "error"
+        ],
+        "properties": {
+          "status": {
+            "type": "string",
+            "enum": [
+              "error"
+            ],
+            "description": "Always `\"error\"` for error responses."
+          },
+          "error": {
+            "type": "string",
+            "description": "Human-readable error message."
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/api-reference/sessions/create.mdx b/api-reference/sessions/create.mdx
new file mode 100644
index 0000000..f73e290
--- /dev/null
+++ b/api-reference/sessions/create.mdx
@@ -0,0 +1,4 @@
+---
+title: "Create Session"
+openapi: "/api-reference/openapi/sessions.json POST /api/sessions"
+---
diff --git a/docs.json b/docs.json
index 0ea3137..57c9737 100644
--- a/docs.json
+++ b/docs.json
@@ -22,13 +22,6 @@
               "mcp",
               "authentication"
             ]
-          },
-          {
-            "group": "Agents",
-            "pages": [
-              "agents",
-              "content-agent"
-            ]
           }
         ]
       },
@@ -60,16 +53,6 @@
             "pages": [
               "api-reference/fans/get"
             ]
-          },
-          {
-            "group": "Tasks",
-            "pages": [
-              "api-reference/tasks/get",
-              "api-reference/tasks/create",
-              "api-reference/tasks/update",
-              "api-reference/tasks/delete",
-              "api-reference/tasks/runs"
-            ]
           }
         ]
       },
@@ -195,7 +178,9 @@
               "api-reference/content/templates",
               "api-reference/content/template-detail",
               "api-reference/content/validate",
-              "api-reference/content/estimate"
+              "api-reference/content/estimate",
+              "api-reference/image/generation",
+              "api-reference/transcribe/audio"
             ]
           },
           {
@@ -204,37 +189,6 @@
               "api-reference/posts/get",
               "api-reference/comments/get"
             ]
-          },
-          {
-            "group": "Content Agent",
-            "pages": [
-              "api-reference/content-agent/webhook",
-              "api-reference/content-agent/callback"
-            ]
-          },
-          {
-            "group": "Image",
-            "pages": [
-              "api-reference/image/generation"
-            ]
-          },
-          {
-            "group": "Transcribe",
-            "pages": [
-              "api-reference/transcribe/audio"
-            ]
-          },
-          {
-            "group": "Sandboxes",
-            "pages": [
-              "api-reference/sandboxes/list",
-              "api-reference/sandboxes/create",
-              "api-reference/sandboxes/snapshot",
-              "api-reference/sandboxes/delete",
-              "api-reference/sandboxes/setup",
-              "api-reference/sandboxes/file",
-              "api-reference/sandboxes/upload"
-            ]
           }
         ]
       },
@@ -266,7 +220,7 @@
         ]
       },
       {
-        "tab": "Accounts",
+        "tab": "Agents & Sandboxes",
         "groups": [
           {
             "group": "Agent Onboarding",
@@ -276,15 +230,52 @@
             ]
           },
           {
-            "group": "Connectors",
+            "group": "Agents",
             "pages": [
-              "api-reference/connectors/list",
-              "api-reference/connectors/authorize",
-              "api-reference/connectors/disconnect",
-              "api-reference/connectors/list-actions",
-              "api-reference/connectors/execute-action"
+              "agents",
+              "content-agent"
+            ]
+          },
+          {
+            "group": "Tasks",
+            "pages": [
+              "api-reference/tasks/get",
+              "api-reference/tasks/create",
+              "api-reference/tasks/update",
+              "api-reference/tasks/delete",
+              "api-reference/tasks/runs"
+            ]
+          },
+          {
+            "group": "Content Agent",
+            "pages": [
+              "api-reference/content-agent/webhook",
+              "api-reference/content-agent/callback"
+            ]
+          },
+          {
+            "group": "Sandboxes",
+            "pages": [
+              "api-reference/sandboxes/list",
+              "api-reference/sandboxes/create",
+              "api-reference/sandboxes/snapshot",
+              "api-reference/sandboxes/delete",
+              "api-reference/sandboxes/setup",
+              "api-reference/sandboxes/file",
+              "api-reference/sandboxes/upload"
             ]
           },
+          {
+            "group": "Sessions",
+            "pages": [
+              "api-reference/sessions/create"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Accounts",
+        "groups": [
           {
             "group": "Pulses",
             "pages": [
@@ -342,6 +333,21 @@
             "pages": [
               "api-reference/notifications/create"
             ]
+          }
+        ]
+      },
+      {
+        "tab": "Tools & Reference",
+        "groups": [
+          {
+            "group": "Connectors",
+            "pages": [
+              "api-reference/connectors/list",
+              "api-reference/connectors/authorize",
+              "api-reference/connectors/disconnect",
+              "api-reference/connectors/list-actions",
+              "api-reference/connectors/execute-action"
+            ]
           },
           {
             "group": "AI",