Conversational File Attachment API

15 min readGuide reference date: October 14, 2026.View original in Notion ↗

Purpose

This API uploads document files and attaches them to a conversation session.

Uploaded files are parsed and converted to text. When chat requests use the same session_id, the AI can reference the file contents as needed.

If session_id is absent, the server issues a new session and attaches the file to it.

1. Session File Upload API

URL

HTTP method

Plain Text

POST

Headers

Headers	Value	Description
Authorization	Bearer <api_key>	Use the API key provided in the Sidetalk dashboard.

For multipart/form-data requests, let the browser or HTTP client set Content-Type and the boundary automatically.

Body

Parameter	Type	Required	Description
file	File	Yes	The document file to upload.
session_id	String	No	The session ID to attach the file to. The server issues one if absent.
sessionId	String	No	An alias for session_id.

Supported file formats

Extension	Description
pdf	PDF document
xlsx	Excel document
xls	Excel document
csv	CSV file
txt	Text file
docx	Word document
doc	Word document
pptx	PowerPoint document
ppt	PowerPoint document

File size limits

File format	Limit
txt, csv	3MB or less
pdf, xlsx, xls, docx, doc, pptx, ppt	20MB or less

session_id policy

Situation	Behavior
No session_id	The server creates a new session_id and attaches the file to it.
session_id provided and valid	Attaches the file to that session.
session_id provided with an invalid format	Returns an error.
session_id provided but does not exist	Returns an error.

The recommended approach is:

If you have session_id from a chat API response, include it with the file upload.
You can also upload a file first without session_id.
In that case, use session_id from the upload response in subsequent chat requests.

Example request

Upload without session_id

JSON

curl -X POST https://api.sidetalk.ai/v1/chat/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "file=@관리자매뉴얼.pdf"

Upload to an existing session

JSON

curl -X POST https://api.sidetalk.ai/v1/chat/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "session_id=943f15db-3984-4f21-ad64-f0115839c3a6" \
  -F "file=@관리자매뉴얼.pdf"

Example success response

JSON

{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "result": {
    "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1",
    "id": 15,
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "file_name": "관리자매뉴얼.pdf",
    "content_chars": 9527,
    "summary_chars": 247
  }
}

Response fields

Field	Type	Description
success	Boolean	Whether the request succeeded.
session_id	String	The session ID the file is attached to, used for subsequent chat requests.
result	Object	Uploaded file information.
result.file_id	String	The unique file ID, which can be used for deletion.
result.id	Number	The internal file ID, included for compatibility.
result.session_id	String	The session ID the file is attached to.
result.file_name	String	The uploaded file name.
result.content_chars	Number	The number of body text characters extracted from the file.
result.summary_chars	Number	The number of characters in the file summary.

2. Chat flow after file upload

Call the chat API with session_id from the upload response.

Step 1. Upload the file

JSON

curl -X POST https://api.sidetalk.ai/v1/chat/files \
  -H "Authorization: Bearer ${API_KEY}" \
  -F "file=@청소기매뉴얼.pdf"

Response:

JSON

{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "result": {
    "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1",
    "id": 15,
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "file_name": "청소기매뉴얼.pdf",
    "content_chars": 9527,
    "summary_chars": 247
  }
}

Step 2. Ask a question with the same session_id

JSON

curl -X POST https://api.sidetalk.ai/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "message": "먼지통 청소 방법 알려줘.",
    "stream": false
  }'

Response:

JSON

{
  "success": true,
  "object": "chat.completion",
  "model": "sidetalk",
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "chat_log_uuid": "2b9cc8fb-3cc6-4d40-aef6-d44af3d074f3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "먼지통 청소 방법은 다음과 같습니다..."
      }
    }
  ]
}

3. File List API

Retrieve the files attached to the current session.

URL

Plain Text

https://api.sidetalk.ai/v1/chat/files

HTTP method

Plain Text

GET

Headers

Headers	Value	Description
Authorization	Bearer <api_key>	Use the API key provided in the Sidetalk dashboard.

Query Parameters

Parameter	Type	Required	Description
session_id	String	Yes	The session ID to query.
sessionId	String	No	An alias for session_id.

Example request

JSON

curl -X GET "https://api.sidetalk.ai/v1/chat/files?session_id=943f15db-3984-4f21-ad64-f0115839c3a6" \
  -H "Authorization: Bearer ${API_KEY}"

Example response

JSON

{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "files": [
    {
      "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1",
      "id": 15,
      "file_name": "청소기매뉴얼.pdf",
      "mime_type": "application/pdf",
      "file_size": 3623117,
      "content_chars": 9527,
      "summary_chars": 247,
      "created_at": "2026-07-14T10:20:30.000Z"
    }
  ]
}

4. File Deletion API

Delete files attached to the current session.

URL

Plain Text

https://api.sidetalk.ai/v1/chat/files

HTTP method

Plain Text

DELETE

Headers

Headers	Value	Description
Content-Type	application/json	Indicates that the request body is JSON.
Authorization	Bearer <api_key>	Use the API key provided in the Sidetalk dashboard.

Body

Parameter	Type	Required	Description
session_id	String	Yes	The session ID the file is attached to.
sessionId	String	No	An alias for session_id.
file_id	String	No	The file ID to delete. If absent, deletes all files in the session.

Example request

Delete a specific file

JSON

curl -X DELETE https://api.sidetalk.ai/v1/chat/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
    "file_id": "file_9e17c4df-5b4a-48c8-8e8f-3de7c6e9c5a1"
  }'

Delete all files in a session

JSON

curl -X DELETE https://api.sidetalk.ai/v1/chat/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_KEY}" \
  -d '{
    "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6"
  }'

Example response

JSON

{
  "success": true,
  "session_id": "943f15db-3984-4f21-ad64-f0115839c3a6",
  "deleted": 1
}

5. JavaScript examples

5-1. Upload a file

JavaScript

async function uploadFile(file, sessionId = "") {
  const formData = new FormData();
  formData.append("file", file);

  if (sessionId) {
    formData.append("session_id", sessionId);
  }

  const response = await fetch("https://api.sidetalk.ai/v1/chat/files", {
    method: "POST",
    headers: {
      "Authorization": "Bearer [API_KEY]"
    },
    body: formData
  });

  const data = await response.json();

  if (!response.ok || !data.success) {
    console.error("File Upload Error:", data.error || "Unknown error");
    return null;
  }

  return {
    sessionId: data.session_id,
    file: data.result
  };
}

5-2. Ask a question after uploading

JavaScript

async function askWithFile(file, question) {
  const uploadResult = await uploadFile(file);

  if (!uploadResult) {
    return null;
  }

  const response = await fetch("https://api.sidetalk.ai/v2/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer [API_KEY]"
    },
    body: JSON.stringify({
      session_id: uploadResult.sessionId,
      message: question,
      stream: false
    })
  });

  const data = await response.json();

  if (!response.ok) {
    console.error("Chat Error:", data.error?.message || "Unknown error");
    return null;
  }

  return {
    sessionId: data.session_id,
    file: uploadResult.file,
    answer: data.choices?.[0]?.message?.content || "",
    chatLogUuid: data.chat_log_uuid || ""
  };
}

5-3. Retrieve the file list

JavaScript

async function getSessionFiles(sessionId) {
  const response = await fetch(
    `https://api.sidetalk.ai/v1/chat/files?session_id=${encodeURIComponent(sessionId)}`,
    {
      method: "GET",
      headers: {
        "Authorization": "Bearer [API_KEY]"
      }
    }
  );

  const data = await response.json();

  if (!response.ok || !data.success) {
    console.error("File List Error:", data.error || "Unknown error");
    return [];
  }

  return data.files || [];
}

5-4. Delete a file

JavaScript

async function deleteSessionFile(sessionId, fileId = "") {
  const body = {
    session_id: sessionId
  };

  if (fileId) {
    body.file_id = fileId;
  }

  const response = await fetch("https://api.sidetalk.ai/v1/chat/files", {
    method: "DELETE",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer [API_KEY]"
    },
    body: JSON.stringify(body)
  });

  const data = await response.json();

  if (!response.ok || !data.success) {
    console.error("File Delete Error:", data.error || "Unknown error");
    return null;
  }

  return data;
}

6. Error responses

File upload API errors are returned in the following format.

JSON

{
  "success": false,
  "error": "Only txt, pdf, xlsx, xls, and csv files are allowed."
}

Main error cases

HTTP status	error	Description
400	file is required	File is missing
400	invalid_session_id_format	session_id has an invalid format
404	session_id_not_found	The provided session_id does not exist for the current site
400	Only txt, pdf, xlsx, xls, and csv files are allowed.	Unsupported file format
400	File size exceeds limit.	File size limit exceeded
403	Authentication error	API authentication failure
500	server_error	An internal server error occurred

7. Notes

The file upload API currently uses /v1/chat/files.
It can be used with the v2 chat API.
Pass session_id from the upload response to the v2 chat API.
If a file is uploaded without session_id, the server issues a new session.
Multiple files can be attached to the same session_id.
During chat, the AI decides whether to reference files based on the question and conversation flow.
The file itself is not stored long term. After parsing, only extracted text and summary information are stored in the session files table.
Use file_id for file-level operations such as deletion.

Conversational File Attachment API

Related documentation

Purpose

1. Session File Upload API

URL

HTTP method

Headers

Body

Supported file formats

File size limits

session_id policy

Example request

Upload without session_id

Upload to an existing session

Example success response

Response fields

2. Chat flow after file upload

Step 1. Upload the file

Step 2. Ask a question with the same session_id

3. File List API

URL

HTTP method

Headers

Query Parameters

Example request

Example response

4. File Deletion API

URL

HTTP method

Headers

Body

Example request

Delete a specific file

Delete all files in a session

Example response

5. JavaScript examples

5-1. Upload a file

5-2. Ask a question after uploading

5-3. Retrieve the file list

5-4. Delete a file

6. Error responses

Main error cases

7. Notes