> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/en/api-reference/fu-jian-he-dang-an.md).

# Attachments and Files

### Create New Attachment (Integrated) <a href="#attachments-upload-create" id="attachments-upload-create"></a>

POST `/api/v1/attachments-upload/`

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/attachments-upload/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// Create a FormData object
const formData = new FormData();
// Replace with the actual file
formData.append('file', /* actual file object */, 'example_file.pdf');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/attachments-upload/", formData, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request error:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/attachments-upload/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# Create file and form data
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/attachments-upload/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 201**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "type"?:  // optional
  {
  }
  "filename": string
  "file": string (uri)
  "expiresAt": string // ISO datetime when this attachment will be auto-deleted.

For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": {},
  "filename": "response string",
  "file": "https://example.com/file.jpg",
  "expiresAt": "response string"
}
```

***

### Get Presigned URL for File Upload <a href="#upload-presigned-url-create" id="upload-presigned-url-create"></a>

POST `/api/v1/upload-presigned-url/`

#### Request Body

**Request Parameters**

| Field     | Type    | Required | Description                                                                                  |
| --------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| modelName | string  | Yes      | Model name, such as attachment、web-chat、faq、organization、chatbot-file、contact、meeting-record |
| fieldName | string  | Yes      | Field name, such as file、logo、avatar、powered-by-logo、answer、compact\_logo、audio              |
| filename  | string  | Yes      | File name, such as example.pdf                                                               |
| fileSize  | integer | Yes      | File size (bytes)                                                                            |

**Request Schema Example**

```typescript
{
  "modelName": string // Model name, such as attachment、web-chat、faq、organization、chatbot-file、contact、meeting-record
  "fieldName": string // Field name, such as file、logo、avatar、powered-by-logo、answer、compact_logo、audio
  "filename": string // File name, such as example.pdf
  "fileSize": integer // File size (bytes)
}
```

**Example Request Values**

```json
{
  "modelName": "attachment",
  "fieldName": "file",
  "filename": "example.pdf",
  "fileSize": 102400
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/upload-presigned-url/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelName": "attachment",
    "fieldName": "file",
    "filename": "example.pdf",
    "fileSize": 102400
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request body (payload)
const data = {
    "modelName": "attachment",
    "fieldName": "file",
    "filename": "example.pdf",
    "fileSize": 102400
  };

axios.post("https://api.maiagent.ai/api/v1/upload-presigned-url/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request error:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/upload-presigned-url/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request body (payload)
data = {
    "modelName": "attachment",
    "fieldName": "file",
    "filename": "example.pdf",
    "fileSize": 102400
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/upload-presigned-url/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'modelName' => 'attachment',
            'fieldName' => 'file',
            'filename' => 'example.pdf',
            'fileSize' => 102400
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "url": string (uri) // Upload target URL (bucket URL for S3/GCS; blob URL with SAS for Azure)
  "fields": object // POST form fields; Azure includes only key
  "method"?:  // POST if absent; Azure Blob returns PUT

* `POST` - POST
* `PUT` - PUT (optional)
  {
  }
  "headers"?: object // Request headers required for PUT (optional)
}
```

**Example Response Values**

```json
{
  "url": "https://s3.example.com/bucket-name",
  "fields": {
    "key": "media/chat/attachment/filename.pdf",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "AKIAXXXXXXXXXXXXXXXX/YYYYMMDD/region/s3/aws4_request",
    "x-amz-date": "YYYYMMDDTHHMMSSZ",
    "policy": "base64-encoded-policy-document",
    "x-amz-signature": "generated-signature-hash"
  }
}
```

***

### Upload Attachment via Presigned URL <a href="#attachments-create" id="attachments-create"></a>

POST `/api/v1/attachments/`

#### Request Body

**Request Parameters**

| Field    | Type         | Required | Description |
| -------- | ------------ | -------- | ----------- |
| type     | object       | No       |             |
| filename | string       | Yes      |             |
| file     | string (uri) | Yes      |             |

**Request Schema Example**

```typescript
{
  "type"?:  // Optional
  {
  }
  "filename": string
  "file": string (uri)
}
```

**Request Example**

```json
{
  "type": {},
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg"
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/attachments/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": {},
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg"
  }'

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "type": {},
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg"
  };

axios.post("https://api.maiagent.ai/api/v1/attachments/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/attachments/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
    "type": {},
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg"
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/attachments/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'type' => new \stdClass(),
            'filename' => 'document.pdf',
            'file' => 'https://example.com/file.jpg'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 201**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "type"?:  // Optional
  {
  }
  "filename": string
  "file": string (uri)
  "expiresAt": string // ISO datetime when this attachment will be auto-deleted.

For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
  "downloadStatus": string
}
```

**Response Example**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": {},
  "filename": "response string",
  "file": "https://example.com/file.jpg",
  "expiresAt": "response string",
  "downloadStatus": "response string"
}
```

***

### Get Specific Attachment <a href="#attachments-retrieve" id="attachments-retrieve"></a>

GET `/api/v1/attachments/{id}/`

#### Parameters

| Parameter | Required | Type   | Description                                |
| --------- | -------- | ------ | ------------------------------------------ |
| `id`      | ✅        | string | A UUID string identifying this attachment. |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Make sure to replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/attachments/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred during the request: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "id": string (uuid)
  "type"?:  // Optional
  {
  }
  "filename": string
  "file": string (uri)
  "expiresAt": string // ISO datetime when this attachment will be auto-deleted.

For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
  "downloadStatus": string
}
```

**Response Example**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": {},
  "filename": "response string",
  "file": "https://example.com/file.jpg",
  "expiresAt": "response string",
  "downloadStatus": "response string"
}
```

***

### Create Conversation Attachment <a href="#conversations-attachments-create" id="conversations-attachments-create"></a>

POST `/api/v1/conversations/{conversationPk}/attachments/`

#### Parameters

| Parameter        | Required | Type   | Description |
| ---------------- | -------- | ------ | ----------- |
| `conversationPk` | ✅        | string |             |

#### Request Body

**Request Parameters**

| Field        | Type          | Required | Description |
| ------------ | ------------- | -------- | ----------- |
| type         | object        | No       |             |
| filename     | string        | Yes      |             |
| file         | string (uri)  | Yes      |             |
| conversation | string (uuid) | No       |             |

**Example Request Schema**

```typescript
{
  "type"?:  // Optional
  {
  }
  "filename": string
  "file": string (uri)
  "conversation"?: string (uuid) // Optional
}
```

**Example Request Values**

```json
{
  "type": {},
  "filename": "document.pdf",
  "file": "https://example.com/file.jpg",
  "conversation": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/attachments/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": {},
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "conversation": "550e8400-e29b-41d4-a716-446655440000"
  }'

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request Body (payload)
const data = {
    "type": {},
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "conversation": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/attachments/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request error:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/attachments/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request Body (payload)
data = {
    "type": {},
    "filename": "document.pdf",
    "file": "https://example.com/file.jpg",
    "conversation": "550e8400-e29b-41d4-a716-446655440000"
}

response = requests.post(url, json=data, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/attachments/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'type' => new \stdClass(),
            'filename' => 'document.pdf',
            'file' => 'https://example.com/file.jpg',
            'conversation' => '550e8400-e29b-41d4-a716-446655440000'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status code: 201**

**Example Response Schema**

```typescript
{
  "id": string (uuid)
  "type"?:  // Optional
  {
  }
  "filename": string
  "file": string (uri)
  "expiresAt": string // ISO datetime when this attachment will be auto-deleted.

For conversation-bound attachments: conversation.last_message_created_at + retention_days.
For attachments without a conversation: created_at + retention_days.
Returns None when cleanup is disabled (effective_from not set).
  "conversation"?: string (uuid) // Optional
  "parser": object
  "parserAutoDetected": boolean
}
```

**Example Response Values**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": {},
  "filename": "Response string",
  "file": "https://example.com/file.jpg",
  "expiresAt": "Response string",
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "parser": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example response name",
    "description": "Example response description"
  },
  "parserAutoDetected": false
}
```

**Status code: 400 - Error codes (X-Error-Code): \`conversation\_attachment\_limit\_reached\`, \`conversation\_attachment\_storage\_limit\_reached\`, \`invalid\`.**

**Status code: 404 - Error codes (X-Error-Code): \`not\_found\`.**

**Status code: 429 - Error codes (X-Error-Code): \`throttled\`.**

***

### Retrieve Allowed File Specifications <a href="#allowed-file-specs-retrieve" id="allowed-file-specs-retrieve"></a>

GET `/api/v1/allowed-file-specs/`

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# Example API call (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/allowed-file-specs/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Replace YOUR_API_KEY and verify the request data before running.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/allowed-file-specs/", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request error:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/allowed-file-specs/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/allowed-file-specs/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response Body

**Status code: 200**

**Example Response Schema**

```typescript
{
  "webChat": object
  "organization": object
  "attachment": object
  "chatbotFile": object
  "knowledgeBaseFile": object
  "batchQa": object
  "meetingRecord": object
  "documentTranslation": object
}
```

**Example Response Values**

```json
{
  "web_chat": {
    "logo": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 5242880
      }
    ],
    "avatar": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 2097152
      }
    ],
    "cover": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 10485760
      }
    ],
    "powered-by-logo": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 5242880
      }
    ]
  },
  "organization": {
    "compact_logo": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 2097152
      }
    ],
    "full_logo": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 2097152
      }
    ]
  },
  "attachment": {
    "file": [
      {
        "content_type": {
          ".pdf": "application/pdf",
          ".doc": "application/msword",
          ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
          ".txt": "text/plain"
        },
        "max_size": 20971520
      },
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif"
        },
        "max_size": 5242880
      }
    ]
  },
  "chatbot_file": {
    "file": [
      {
        "content_type": {
          ".pdf": "application/pdf",
          ".doc": "application/msword",
          ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
          ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          ".ppt": "application/vnd.ms-powerpoint",
          ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
          ".txt": "text/plain"
        },
        "max_size": 104857600
      }
    ]
  },
  "batch_qa": {
    "file": [
      {
        "content_type": null,
        "max_size": 104857600
      }
    ]
  },
  "faq": {
    "answer": [
      {
        "content_type": {
          ".jpg": "image/jpeg",
          ".jpeg": "image/jpeg",
          ".png": "image/png",
          ".gif": "image/gif",
          ".webp": "image/webp",
          ".tiff": "image/tiff",
          ".mp4": "video/mp4"
        },
        "max_size": 104857600
      }
    ]
  }
}
```

***

### List Conversation Attachments <a href="#file-library-conversation-attachments-list" id="file-library-conversation-attachments-list"></a>

GET `/api/v1/file-library/conversation-attachments/`

{% hint style="info" %}
**Required permissions**: The organization has the file library enabled, and the caller's role has any file library permission. For the visible scope and how `expiresAt` is calculated, see the technical manual [Conversation Attachment Management API](https://docs.maiagent.ai/tech/api-integration/endpoint-behaviors/conversation-attachments)。
{% endhint %}

#### Parameters

| Parameter Name | Required | Type    | Description                                    |
| -------------- | -------- | ------- | ---------------------------------------------- |
| `page`         | ❌        | integer | A page number within the paginated result set. |
| `pageSize`     | ❌        | integer | Number of results to return per page.          |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/file-library/conversation-attachments/?page=1&pageSize=1" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please make sure to replace YOUR_API_KEY and verify the request data before executing.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/file-library/conversation-attachments/?page=1&pageSize=1", config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request error occurred:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/file-library/conversation-attachments/?page=1&pageSize=1"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error occurred:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/file-library/conversation-attachments/?page=1&pageSize=1", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error occurred: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

**Status Code: 200**

**Response Schema Example**

```typescript
{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "filename": string
      "fileSize": integer
      "type": 
      {
      }
      "conversationId": string (uuid)
      "expiresAt": string
      "createdAt": string (timestamp)
    }
  ]
}
```

**Response Example Values**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "Response string",
      "fileSize": 456,
      "type": {},
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "expiresAt": "Response string",
      "createdAt": "Response string"
    }
  ]
}
```

***

### Delete Conversation Attachment <a href="#file-library-conversation-attachments-destroy" id="file-library-conversation-attachments-destroy"></a>

DELETE `/api/v1/file-library/conversation-attachments/{id}/`

{% hint style="info" %}
**Required permissions**: Same as "List Conversation Attachments". You can only delete attachments visible to the caller; other attachments return 404. Deleting also removes the stored file if no other attachment or file shares it.
{% endhint %}

#### Parameters

| Parameter Name | Required | Type   | Description |
| -------------- | -------- | ------ | ----------- |
| `id`           | ✅        | string |             |

#### Code Examples

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API call example (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/file-library/conversation-attachments/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please make sure to replace YOUR_API_KEY and verify the request data before executing.
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// Request body (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/file-library/conversation-attachments/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('Response received successfully:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('Request error occurred:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/file-library/conversation-attachments/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("Response received successfully:")
    print(response.json())
except Exception as e:
    print("Request error occurred:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/file-library/conversation-attachments/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request error occurred: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### Response

| Status Code | Description      |
| ----------- | ---------------- |
| 204         | No response body |

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/en/api-reference/fu-jian-he-dang-an.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.