# Media Album

Media albums contain audio, video, and images with captions and tagging. Below are the fields and endpoints for working with media albums in the API.

:::note
Media albums exist in groups and sections.
:::

## Fields

| Field                 | Name                  | Description                                                                | Type      |
| --------------------- | --------------------- | -------------------------------------------------------------------------- | --------- |
| `Title`*              | `title`               | The album title.                                                           | `string`  |
| `Description`         | `description`         | The album description.                                                     | `string`  |
| `Comments setting`    | `setting_comments`    | Whether or not comments are enabled for media album content (`0` or `1`).  | `{0,1}`   |
| `Member post setting` | `setting_member_post` | Whether or not non-admins can add content to the media album (`0` or `1`). | `{0,1}`   |
| `Published`           | `published`           | Whether or not the media album is published (`0` or `1`).                  | `{0,1}`   |
| `Photo count`         | `photo_count`         | The number of images in the album.                                         | `integer` |
| `Video count`         | `video_count`         | The number of video files in the album.                                    | `integer` |
| `Audio count`         | `audio_count`         | The number of audio files in the album.                                    | `integer` |
| `Cover image URL`     | `cover_image_url`     | The full URL of the cover image.                                           | `string`  |
| `Created timestamp`   | `created`             | The unix timestamp when the media album was created.                       | `integer` |

\* = Required

## GET `{realm}/albums`

View a list of albums for the given realm. Optional query parameter:

- `withcontent=1`: include the contents of the album in the response

**Return** A list of [album](#fields) objects

```json
{
  "album": [
    {
      "id": 5692169,
      "title": "My media album",
      "description": "",
      "setting_comments": 1,
      "setting_member_post": 0,
      "photo_count": 0,
      "video_count": 0,
      "audio_count": 0,
      "created": 1388170669,
      "available": 1,
      "completed": 0,
      "completion_status": "",
      "links": {
        "self": "http:\/\/...\/v1\/album\/5692169"
      }
    }
  ],
  "total": 1,
  "links": {
    "self": "http:\/\/...\/albums?start=0&limit=20"
  }
}
```

```xml
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <album>
        <id>5692169</id>
        <title>My media album</title>
        <description />
        <setting_comments>1</setting_comments>
        <setting_member_post>0</setting_member_post>
        <photo_count>0</photo_count>
        <video_count>0</video_count>
        <audio_count>0</audio_count>
        <created>1388170669</created>
        <available>1</available>
        <completed>0</completed>
        <completion_status />
        <links>
            <self>http://.../v1/album/5692169</self>
        </links>
    </album>
    <total>1</total>
    <links>
        <self>http://.../albums?start=0&amp;limit=20</self>
    </links>
</result>
```

## GET `{realm}/albums/{id}`

View a specified album

**Return** An [album](#fields)

```json
{
  "album": [
    {
      "id": 5692169,
      "title": "My media album",
      "description": "",
      "setting_comments": 1,
      "setting_member_post": 0,
      "photo_count": 0,
      "video_count": 0,
      "audio_count": 0,
      "created": 1388170669,
      "available": 1,
      "completed": 0,
      "completion_status": "",
      "links": {
        "self": "http:\/\/...\/v1\/album\/5692169"
      }
    }
  ],
  "total": 1,
  "links": {
    "self": "http:\/\/...\/albums?start=0&limit=20"
  }
}
```

```xml
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <album>
        <id>5692169</id>
        <title>My media album</title>
        <description />
        <setting_comments>1</setting_comments>
        <setting_member_post>0</setting_member_post>
        <photo_count>0</photo_count>
        <video_count>0</video_count>
        <audio_count>0</audio_count>
        <created>1388170669</created>
        <available>1</available>
        <completed>0</completed>
        <completion_status />
        <links>
            <self>http://.../v1/album/5692169</self>
        </links>
    </album>
    <total>1</total>
    <links>
        <self>http://.../albums?start=0&amp;limit=20</self>
    </links>
</result>
```

## GET `{realm}/albums/{id}/content/{id}`

View specified album content

**Return** An [album](#fields)

```json
{
  "album": [
    {
      "id": 5692169,
      "title": "My media album",
      "description": "",
      "setting_comments": 1,
      "setting_member_post": 0,
      "photo_count": 1,
      "video_count": 0,
      "audio_count": 0,
      "created": 1388170669,
      "available": 1,
      "completed": 0,
      "cover_image_url": "http:\/\/...\/52bdcf1fa3119.jpg",
      "completion_status": "",
      "links": {
        "self": "http:\/\/...\/v1\/album\/5692169"
      }
    }
  ],
  "total": 1,
  "links": {
    "self": "http:\/\/...\/albums?start=0&limit=20"
  }
}
```

```xml
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <album>
        <id>5692169</id>
        <title>My media album</title>
        <description />
        <setting_comments>1</setting_comments>
        <setting_member_post>0</setting_member_post>
        <photo_count>1</photo_count>
        <video_count>0</video_count>
        <audio_count>0</audio_count>
        <created>1388170669</created>
        <available>1</available>
        <completed>0</completed>
        <cover_image_url>http://.../52bdcf1fa3119.jpg</cover_image_url>
        <completion_status />
        <links>
            <self>http://.../v1/album/5692169</self>
        </links>
    </album>
    <total>1</total>
    <links>
        <self>http://.../albums?start=0&amp;limit=20</self>
    </links>
</result>
```

## POST `{realm}/albums`

Create an album

**Content** An object containing album fields

```json
{
  "title": "This album was created through api",
  "description": "this is new api media album",
  "setting_comments": "1",
  "setting_member_post": "1",
  "published": "1"
}
```

```xml
<body>
  <title>This album was created through api</title>
  <description>this is new api media album</description>
  <setting_comments>1</setting_comments>
  <setting_member_post>1</setting_member_post>
  <published>1</published>
</body>
```

**Return** The created album object

```json
{
  "id": 5692169,
  "title": "My media album",
  "description": "This is a media album",
  "setting_comments": 1,
  "setting_member_post": 0,
  "photo_count": 0,
  "video_count": 0,
  "audio_count": 0,
  "created": 1388170669,
  "available": 1,
  "completed": 0,
  "links": {
    "self": "http:\/\/...\/v1\/album\/5692169"
  }
}
```

```xml
<?xml version="1.0" encoding="utf-8" ?>
<result>
	<id>5692169</id>
	<title>My media album</title>
	<description>This is a media album</description>
	<setting_comments>1</setting_comments>
	<setting_member_post>0</setting_member_post>
	<photo_count>0</photo_count>
	<video_count>0</video_count>
	<audio_count>0</audio_count>
	<created>1388170669</created>
	<available>1</available>
	<completed>0</completed>
	<links>
		<self>http://.../v1/album/5692169</self>
	</links>
</result>
```

## POST `{realm}/albums/{id}/content`

Create album content. For file uploading details see File Uploading.

**Content** Example request with file-attachment and extras

```json
{
  "file-attachment": {
    "id": [213123234, 213123235]
  },
  "extras": [
    {
      "fid": 213123234,
      "caption": "A beautiful view",
      "display_order": 1
    },
    {
      "fid": 213123235,
      "caption": "A beautiful view again",
      "display_order": 2
    }
  ]
}
```

```xml
<body>
   <extras>
      <extra>
         <caption>A beautiful view</caption>
         <fid>213123234</fid>
         <display_order>1</display_order>
      </extra>
      <extra>
         <caption>A beautiful view again</caption>
         <fid>213123235</fid>
         <display_order>2</display_order>
      </extra>
   </extras>
   <file-attachment>
      <id>
         <id>213123234</id>
         <id>213123235</id>
      </id>
   </file-attachment>
</body>
```

**Return** Created content objects

```json
{
  "content": [
    {
      "id": 17861,
      "album_id": 5692169,
      "type": "image",
      "caption": "A beautiful view",
      "display_order": 2,
      "created": 1388171561,
      "album_cover": 0,
      "converted_url": null,
      "converted_filesize": null,
      "converted_md5_checksum": null,
      "content_url": "http:\/\/...\/5692169\/52bdd12925164.jpg",
      "content_filesize": "3825",
      "content_md5_checksum": "69392e30b6",
      "thumbnail_url": "http:\/\/...\/5692169\/52bdd12925164.jpg",
      "thumbnail_dimensions": "172x172",
      "content_dimensions": "600x600"
    }
  ]
}
```

```xml
<?xml version="1.0" encoding="utf-8" ?>
<result>
    <content>
        <id>17861</id>
        <album_id>5692169</album_id>
        <type>image</type>
        <caption />
        <display_order>2</display_order>
        <created>1388171561</created>
        <album_cover>0</album_cover>
        <converted_url />
        <converted_filesize />
        <converted_md5_checksum />
        <content_url>http://.../5692169/52bdd12925164.jpg</content_url>
        <content_filesize>3825</content_filesize>
        <content_md5_checksum>69392e30b6</content_md5_checksum>
        <thumbnail_url>http://.../5692169/52bdd12925164.jpg</thumbnail_url>
        <thumbnail_dimensions>172x172</thumbnail_dimensions>
        <content_dimensions>600x600</content_dimensions>
    </content>
</result>
```

## PUT `{realm}/albums/{id}`

Update a specified album

**Content** An object containing album fields to update

```json
{
  "description": "this new album does not allow comments",
  "setting_comments": "0"
}
```

```xml
<body>
  <description>this new album does not allow comments</description>
  <setting_comments>0</setting_comments>
</body>
```

## PUT `{realm}/albums/{id}/content/{id}`

Update specified album content

**Content** An object containing album content fields

```json
{
  "caption": "See my caption text"
}
```

```xml
<body>
  <caption>See my caption text</caption>
</body>
```

## DELETE `{realm}/albums/{id}`

Delete an album (cannot be undone)

## DELETE `{realm}/albums/{id}/content/{id}`

Delete album content (cannot be undone)