# Confluence REST API v1 - Endpoints for AImpress Tasks

**Based on:** https://developer.atlassian.com/cloud/confluence/rest/v1/

---

## WEEK 2: Confluence Spaces & Pages

### Task 1: Create Confluence Spaces

#### 1.1 Create a Space
```bash
POST /wiki/rest/api/space
```

**Request Body:**
```json
{
  "key": "WIKI",
  "name": "Company Wiki",
  "description": {
    "plain": {
      "value": "Company handbook, policies, and SOPs"
    }
  },
  "type": "global"
}
```

**Response:** Returns space object with `id` field (needed for creating pages)

---

#### 1.2 Get All Spaces
```bash
GET /wiki/rest/api/space
```

**Query Parameters:**
- `limit=25` (default, max 250)
- `start=0` (for pagination)

**Response:** Returns list of spaces with their IDs and keys

---

#### 1.3 Get Specific Space
```bash
GET /wiki/rest/api/space/{spaceKey}
```

**Example:**
```bash
GET /wiki/rest/api/space/WIKI
```

---

### Task 2: Create Pages in Spaces

#### 2.1 Create a Page
```bash
POST /wiki/rest/api/pages
```

**Request Body:**
```json
{
  "spaceId": "<space_id_from_create_space>",
  "status": "current",
  "title": "Getting Started",
  "body": {
    "representation": "storage",
    "value": "<p>Welcome to Company Wiki</p>"
  },
  "parentId": null
}
```

**Required Fields:**
- `spaceId` - Get from space creation response
- `title` - Page title
- `body.representation` - Use "storage" format
- `body.value` - HTML content in storage format
- `status` - "current" or "draft"

**Response:** Returns page object with `id` field

---

#### 2.2 Create Child Page (Hierarchy)
```bash
POST /wiki/rest/api/pages
```

**Same as 2.1, but add parentId:**
```json
{
  "spaceId": "<space_id>",
  "status": "current",
  "title": "Subpage Title",
  "body": {
    "representation": "storage",
    "value": "<p>Subpage content</p>"
  },
  "parentId": "<parent_page_id>"
}
```

---

#### 2.3 Get Pages in Space
```bash
GET /wiki/rest/api/pages
```

**Query Parameters:**
- `spaceId=<space_id>` - Filter by space
- `limit=25` - Results per page
- `start=0` - Pagination offset

**Response:** Returns list of pages with their IDs

---

#### 2.4 Get Specific Page
```bash
GET /wiki/rest/api/pages/{pageId}
```

**Query Parameters:**
- `body-format=storage` - Get content in storage format
- `expand=body.storage,history` - Expand specific fields

---

#### 2.5 Update Page
```bash
PUT /wiki/rest/api/pages/{pageId}
```

**Request Body:**
```json
{
  "id": "<page_id>",
  "status": "current",
  "title": "Updated Title",
  "spaceId": "<space_id>",
  "body": {
    "representation": "storage",
    "value": "<p>Updated content</p>"
  },
  "version": {
    "number": 1
  }
}
```

**Note:** Must include current version number to avoid conflicts

---

#### 2.6 Delete Page
```bash
DELETE /wiki/rest/api/pages/{pageId}
```

**Query Parameters:**
- `purge=true` - Permanently delete instead of trash

---

### Task 3: Create Page Templates

#### 3.1 Create Page Template
```bash
POST /wiki/rest/api/templates
```

**Request Body:**
```json
{
  "name": "Meeting Notes",
  "spaceId": "<space_id>",
  "body": {
    "representation": "storage",
    "value": "<h1>Meeting Notes</h1><h2>Date</h2><p>{{date}}</p><h2>Attendees</h2><p></p><h2>Topics</h2><ul><li></li></ul><h2>Action Items</h2><ul><li></li></ul>"
  }
}
```

---

#### 3.2 Get Templates in Space
```bash
GET /wiki/rest/api/templates
```

**Query Parameters:**
- `spaceId=<space_id>` - Filter by space
- `limit=25`
- `start=0`

---

#### 3.3 Get Specific Template
```bash
GET /wiki/rest/api/templates/{templateId}
```

---

#### 3.4 Create Page from Template
```bash
POST /wiki/rest/api/pages
```

**Request Body:**
```json
{
  "spaceId": "<space_id>",
  "status": "current",
  "title": "Q4 Planning",
  "body": {
    "representation": "storage",
    "value": "<h1>Q4 Planning</h1><p>Template content...</p>"
  }
}
```

---

## Additional Confluence Endpoints

### Attachments
```bash
POST /wiki/rest/api/pages/{pageId}/attachments
```

**Use for:** Adding files to pages

---

### Labels
```bash
POST /wiki/rest/api/pages/{pageId}/labels
```

**Use for:** Tagging pages

---

### Content Search
```bash
GET /wiki/rest/api/pages
```

**Query Parameters:**
- `title-contains=keyword` - Search by title
- `spaceId=<space_id>` - Filter by space

---

### Permissions
```bash
GET /wiki/rest/api/spaces/{spaceId}/permissions
POST /wiki/rest/api/spaces/{spaceId}/permissions
```

**Use for:** Managing space access

---

## Summary of Endpoints for Tasks

| Task | HTTP Method | Endpoint | Purpose |
|------|-------------|----------|---------|
| **Task 1: Create Spaces** |
| Create space | POST | `/wiki/rest/api/space` | Create WIKI, PRODOCS, MARKET, SUPPORT |
| Get all spaces | GET | `/wiki/rest/api/space` | Verify spaces created |
| Get space details | GET | `/wiki/rest/api/space/{key}` | Get space ID |
| **Task 2: Create Pages** |
| Create page | POST | `/wiki/rest/api/pages` | Create pages in each space |
| Get pages | GET | `/wiki/rest/api/pages` | List pages in space |
| Get page | GET | `/wiki/rest/api/pages/{id}` | Get page content |
| Update page | PUT | `/wiki/rest/api/pages/{id}` | Edit page content |
| Delete page | DELETE | `/wiki/rest/api/pages/{id}` | Remove pages |
| **Task 3: Templates** |
| Create template | POST | `/wiki/rest/api/templates` | Create 4 templates |
| Get templates | GET | `/wiki/rest/api/templates` | List templates |
| Get template | GET | `/wiki/rest/api/templates/{id}` | Get template details |

---

## API Authentication

All requests require Basic Auth:

```bash
Authorization: Basic $(echo -n "email:token" | base64)
```

---

## Content Representation Format

Use **"storage"** format for API:

```
<h1>Heading</h1>
<p>Paragraph</p>
<ul>
  <li>List item</li>
</ul>
<a href="link">Link text</a>
```

---

## Rate Limits

- Rate limit: 50 requests per second per user
- Wait if you hit limit before retrying

---

**Documentation:** https://developer.atlassian.com/cloud/confluence/rest/v1/
