## Authentication

All API endpoints require session authentication. You must be logged in via the web interface, or send the session cookie with your requests.

For programmatic access, authenticate first:

```bash
# Login and save cookies
curl -c cookies.txt -X POST https://your-yando-instance/accounts/login/ \
  -d "login=user@example.com&password=yourpassword" \
  -H "Referer: https://your-yando-instance/"
```

Then include `-b cookies.txt` in subsequent requests.

## Rate Limiting

API endpoints are rate-limited per user. If you exceed the rate limit, you'll receive a 429 response.

---

## POST /api/boards/import/

Create a new board from exported JSON data.

### Request

Accepts two content types:

**JSON body** (`application/json`):

```bash
curl -b cookies.txt -X POST https://your-yando-instance/api/boards/import/ \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <token>" \
  -d @board-export.json
```

**File upload** (`multipart/form-data`):

```bash
curl -b cookies.txt -X POST https://your-yando-instance/api/boards/import/ \
  -H "X-CSRFToken: <token>" \
  -F "json_file=@board-export.json"
```

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `template` | string | Template name or UUID to override the JSON template |
| `title` | string | Override the board title from the JSON |
| `description` | string | Override the board description |

### Response (201 Created)

```json
{
  "id": "a1b2c3d4-...",
  "title": "My Board",
  "description": "Board description",
  "template": "Business Model Canvas",
  "object_count": 15,
  "url": "/boards/a1b2c3d4-.../"
}
```

### Errors

| Status | Description |
|--------|-------------|
| 400 | Invalid JSON, validation error, or missing required fields |
| 403 | Authentication required |

---

## POST /api/boards/{board_id}/resize/

Resize a board's canvas dimensions.

### Request

```bash
curl -b cookies.txt -X POST \
  https://your-yando-instance/api/boards/{board_id}/resize/ \
  -H "Content-Type: application/json" \
  -H "X-CSRFToken: <token>" \
  -d '{"width": 4000, "height": 2400}'
```

### Response (200 OK)

```json
{
  "id": "a1b2c3d4-...",
  "canvas_width": 4000,
  "canvas_height": 2400
}
```

---

## GET /api/boards/{board_id}/snapshots/

List all snapshots for a board, ordered by creation date (newest first).

### Request

```bash
curl -b cookies.txt \
  https://your-yando-instance/api/boards/{board_id}/snapshots/
```

### Response (200 OK)

```json
[
  {
    "id": "s1n2a3p4-...",
    "created_at": "2026-02-21T08:00:00Z",
    "object_count": 24,
    "board_version": 15,
    "change_summary": {
      "added": {"sticky_note": 2},
      "edited": {"text_box": 1},
      "deleted": {}
    }
  }
]
```

---

## GET /api/boards/{board_id}/snapshots/{snapshot_id}/

Retrieve a single snapshot's full data.

### Request

```bash
curl -b cookies.txt \
  https://your-yando-instance/api/boards/{board_id}/snapshots/{snapshot_id}/
```

### Response (200 OK)

Returns the full snapshot including `snapshot_data` containing the complete board state at that point in time.

---

## POST /api/projects/{project_id}/pages/import/

Import markdown files as project pages.

### Request

Upload one or more `.md` or `.markdown` files:

```bash
curl -b cookies.txt -X POST \
  https://your-yando-instance/api/projects/{project_id}/pages/import/ \
  -H "X-CSRFToken: <token>" \
  -F "files=@notes.md" \
  -F "files=@planning.md"
```

### Response (201 Created)

```json
{
  "pages_created": 2,
  "pages": [
    {
      "id": "p1a2g3e4-...",
      "title": "Notes",
      "url": "/projects/.../pages/p1a2g3e4-.../"
    }
  ],
  "errors": []
}
```

### Status Codes

| Status | Description |
|--------|-------------|
| 201 | All files imported successfully |
| 207 | Partial success - some files imported, some had errors |
| 400 | No files provided or all files failed |
| 403 | Not an owner or editor of the project |
| 404 | Project not found |

---

## JSON Export Schema Reference

When exporting a board to JSON, the structure is:

```json
{
  "board": {
    "title": "Board Title",
    "description": "Optional description",
    "template": "Template Name or null",
    "canvas_width": 3200,
    "canvas_height": 1800
  },
  "zones": {
    "Zone Name": [
      {
        "type": "sticky_note",
        "x": 100,
        "y": 200,
        "width": 200,
        "height": 150,
        "rotation": 0,
        "data": {
          "text": "Content here",
          "color": "#FFEB3B"
        }
      }
    ]
  },
  "unzoned_objects": [
    {
      "type": "text_box",
      "x": 500,
      "y": 100,
      "width": 300,
      "height": 50,
      "data": {
        "text": "Unzoned text"
      }
    }
  ]
}
```

### Object Types

| Type | Data Fields |
|------|-------------|
| `sticky_note` | `text`, `color` |
| `text_box` | `text`, `fontSize`, `fontWeight` |
| `shape` | `shapeType` (`rectangle`, `circle`, `triangle`, `line`), `fill`, `stroke` |