First draft of docs

docs/api/branches.mdx

@@ -0,0 +1,192 @@
+---
+title: Branches API
+description: Manage database branches and their settings
+---
+
+The Branches API allows you to manage your database branches, including listing, creating, updating, and deleting branches.
+
+## List branches
+
+Retrieves a list of all branches within a project.
+
+```bash
+GET /organizations/{organizationID}/projects/{projectID}/branches
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+| projectID | string | Unique identifier for the project |
+
+### Response
+
+```json
+{
+  "branches": [
+    {
+      "id": "br_123",
+      "name": "main",
+      "createdAt": "2024-01-01T00:00:00Z",
+      "updatedAt": "2024-01-01T00:00:00Z",
+      "region": "us-east-1",
+      "publicAccess": false,
+      "description": "Main branch"
+    }
+  ]
+}
+```
+
+## Create branch
+
+Creates a new branch within a project. Branches can be created from scratch or derived from an existing parent branch.
+
+```bash
+POST /organizations/{organizationID}/projects/{projectID}/branches
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+| projectID | string | Unique identifier for the project |
+
+### Request Body
+
+```json
+{
+  "name": "new-branch",
+  "description": "Development branch",
+  "parentID": "br_123",
+  "configuration": {
+    "image": "postgresql:16",
+    "instanceType": "standard",
+    "instances": 1,
+    "region": "us-east-1",
+    "storage": 10
+  }
+}
+```
+
+### Response
+
+```json
+{
+  "id": "br_456",
+  "name": "new-branch",
+  "createdAt": "2024-01-01T00:00:00Z",
+  "updatedAt": "2024-01-01T00:00:00Z",
+  "region": "us-east-1",
+  "publicAccess": false,
+  "description": "Development branch",
+  "connectionString": "postgresql://..."
+}
+```
+
+## Get branch
+
+Retrieves detailed information about a specific branch.
+
+```bash
+GET /organizations/{organizationID}/projects/{projectID}/branches/{branchID}
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+| projectID | string | Unique identifier for the project |
+| branchID | string | Unique identifier for the branch |
+
+### Response
+
+```json
+{
+  "id": "br_123",
+  "name": "main",
+  "createdAt": "2024-01-01T00:00:00Z",
+  "updatedAt": "2024-01-01T00:00:00Z",
+  "region": "us-east-1",
+  "publicAccess": false,
+  "description": "Main branch",
+  "connectionString": "postgresql://...",
+  "status": {
+    "status": "healthy",
+    "instanceCount": 1,
+    "instanceReadyCount": 1,
+    "instances": [
+      {
+        "id": "inst_123",
+        "status": "ready"
+      }
+    ],
+    "lifecycle": {
+      "phase": "running"
+    }
+  }
+}
+```
+
+## Update branch
+
+Updates the configuration of a branch.
+
+```bash
+PATCH /organizations/{organizationID}/projects/{projectID}/branches/{branchID}
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+| projectID | string | Unique identifier for the project |
+| branchID | string | Unique identifier for the branch |
+
+### Request Body
+
+```json
+{
+  "name": "updated-branch",
+  "description": "Updated description",
+  "instances": 2,
+  "storage": 20
+}
+```
+
+### Response
+
+```json
+{
+  "id": "br_123",
+  "name": "updated-branch",
+  "createdAt": "2024-01-01T00:00:00Z",
+  "updatedAt": "2024-01-01T00:00:00Z",
+  "region": "us-east-1",
+  "publicAccess": false,
+  "description": "Updated description"
+}
+```
+
+## Delete branch
+
+Permanently deletes a branch and all its associated data. This action cannot be undone.
+
+```bash
+DELETE /organizations/{organizationID}/projects/{projectID}/branches/{branchID}
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+| projectID | string | Unique identifier for the project |
+| branchID | string | Unique identifier for the branch |
+
+### Response
+
+Returns a 204 status code with no content on success. 

docs/api/index.mdx

@@ -0,0 +1,74 @@
+---
+title: REST API
+description: Interact with Xata programmatically using our REST API
+---
+
+The Xata REST API allows you to programmatically manage your databases, branches, and data. All API endpoints are available at `https://api.xata.tech`.
+
+## Authentication
+
+All API requests require authentication using an API key. You can create API keys in the [Xata dashboard](https://app.xata.io). Include your API key in the `Authorization` header:
+
+```bash
+curl -H "Authorization: Bearer YOUR_API_KEY" https://api.xata.tech/...
+```
+
+## Available Endpoints
+
+The API is organized into the following sections:
+
+### Organizations
+
+- [List organizations](/api/organizations#list-organizations)
+- [Get organization details](/api/organizations#get-organization)
+- [Update organization](/api/organizations#update-organization)
+- [Delete organization](/api/organizations#delete-organization)
+
+### Projects
+
+- [List projects](/api/projects#list-projects)
+- [Create project](/api/projects#create-project)
+- [Get project details](/api/projects#get-project)
+- [Update project](/api/projects#update-project)
+- [Delete project](/api/projects#delete-project)
+- [Get available regions](/api/projects#get-regions)
+
+### Branches
+
+- [List branches](/api/branches#list-branches)
+- [Create branch](/api/branches#create-branch)
+- [Get branch details](/api/branches#get-branch)
+- [Update branch](/api/branches#update-branch)
+- [Delete branch](/api/branches#delete-branch)
+
+## Error Handling
+
+The API uses standard HTTP status codes to indicate the success or failure of requests:
+
+- `200 OK`: The request was successful
+- `201 Created`: A new resource was successfully created
+- `400 Bad Request`: The request was malformed or contained invalid parameters
+- `401 Unauthorized`: Authentication failed or is missing
+- `404 Not Found`: The requested resource does not exist
+- `5XX`: Server error
+
+Error responses include a JSON object with a `message` field describing the error:
+
+```json
+{
+  "message": "Error description"
+}
+```
+
+## Rate Limiting
+
+API requests are subject to rate limiting. The current limits are:
+
+- 100 requests per minute per API key
+- 1000 requests per hour per API key
+
+Rate limit headers are included in all responses:
+
+- `X-RateLimit-Limit`: The maximum number of requests allowed per time window
+- `X-RateLimit-Remaining`: The number of requests remaining in the current time window
+- `X-RateLimit-Reset`: The time when the current rate limit window resets (Unix timestamp)

docs/api/organizations.mdx

@@ -0,0 +1,105 @@
+---
+title: Organizations API
+description: Manage organizations and their settings
+---
+
+The Organizations API allows you to manage your Xata organizations, including listing, creating, updating, and deleting organizations.
+
+## List organizations
+
+Retrieves a list of all organizations you have access to.
+
+```bash
+GET /organizations
+```
+
+### Response
+
+```json
+{
+  "organizations": [
+    {
+      "id": "org_123",
+      "name": "My Organization",
+      "createdAt": "2024-01-01T00:00:00Z",
+      "updatedAt": "2024-01-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+## Get organization
+
+Retrieves detailed information about a specific organization.
+
+```bash
+GET /organizations/{organizationID}
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+
+### Response
+
+```json
+{
+  "id": "org_123",
+  "name": "My Organization",
+  "createdAt": "2024-01-01T00:00:00Z",
+  "updatedAt": "2024-01-01T00:00:00Z"
+}
+```
+
+## Update organization
+
+Updates the name of an organization.
+
+```bash
+PATCH /organizations/{organizationID}
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+
+### Request Body
+
+```json
+{
+  "name": "New Organization Name"
+}
+```
+
+### Response
+
+```json
+{
+  "id": "org_123",
+  "name": "New Organization Name",
+  "createdAt": "2024-01-01T00:00:00Z",
+  "updatedAt": "2024-01-01T00:00:00Z"
+}
+```
+
+## Delete organization
+
+Permanently deletes an organization and all its associated data. This action cannot be undone.
+
+```bash
+DELETE /organizations/{organizationID}
+```
+
+### Path Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| organizationID | string | Unique identifier for the organization |
+
+### Response
+
+Returns a 204 status code with no content on success.