Skip to content
GhostMind

Files & Attachments

Files can be attached to chat completion requests to provide additional context to the AI. This includes documents, code, images, and data files.

Upload Workflow

Files must be uploaded to a conversation before they can be referenced in a chat request. The workflow is:

  1. Create or use an existing conversation
  2. Upload the file via multipart POST
  3. Reference the returned file_id in the chat request’s attachment_file_ids

Step 1: Upload a File

Terminal window
curl -X POST "https://ghostmind.optdmsa.com/v1/conversations/$CONV_ID/attachments" \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -F "file=@document.pdf"

Response:

{
  "file_id": "file_abc123",
  "asset_id": "a1b2c3d4-...",
  "file_name": "document.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 102400
}

Step 2: Send a Chat Request with the File

Terminal window
curl -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-GhostMind-Conversation-Id: $CONV_ID" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "Summarize the uploaded document."}],
    "attachment_file_ids": ["file_abc123"]
  }'

Python Example

import requests


BASE = "https://ghostmind.optdmsa.com"
KEY = "$GHOSTMIND_API_KEY"
CONV_ID = "your-conversation-id"


# Upload a file
with open("report.pdf", "rb") as f:
    upload_resp = requests.post(
        f"{BASE}/v1/conversations/{CONV_ID}/attachments",
        headers={"Authorization": f"Bearer {KEY}"},
        files={"file": ("report.pdf", f, "application/pdf")},
    )
file_id = upload_resp.json()["file_id"]


# Chat with the file
chat_resp = requests.post(
    f"{BASE}/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {KEY}",
        "Content-Type": "application/json",
        "X-GhostMind-Conversation-Id": CONV_ID,
    },
    json={
        "model": "auto",
        "messages": [{"role": "user", "content": "What is in this file?"}],
        "attachment_file_ids": [file_id],
    },
)
print(chat_resp.json()["choices"][0]["message"]["content"])

JavaScript Example

const formData = new FormData();
formData.append("file", fileInput.files[0]);


const uploadResp = await fetch(
  `https://ghostmind.optdmsa.com/v1/conversations/${convId}/attachments`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
    body: formData,
  }
);
const { file_id } = await uploadResp.json();


const chatResp = await fetch("https://ghostmind.optdmsa.com/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
    "X-GhostMind-Conversation-Id": convId,
  },
  body: JSON.stringify({
    model: "auto",
    messages: [{ role: "user", content: "Describe this file." }],
    attachment_file_ids: [file_id],
  }),
});

Inline Image Input

The OpenAI-style content array with image_url and base64 data URLs is accepted for SDK compatibility, but may not be processed by ChatGPT vision depending on the upstream account. For reliable image input, use the attachments workflow (upload + attachment_file_ids) described above.

Terminal window
# This format is accepted but may be silently ignored by ChatGPT
# Prefer the attachments workflow for reliable image input
curl -X POST https://ghostmind.optdmsa.com/v1/chat/completions \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "What color is this image?"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR..."}}
      ]
    }]
  }'

Warning: HTTP 200 does not guarantee the image was processed. If the assistant’s response doesn’t reference the image content, use the attachments workflow instead.

Supported File Types

CategoryTypes
DocumentsPDF, TXT, Markdown
ImagesPNG, JPEG, GIF, WebP
CodePython, JavaScript, TypeScript, etc.
DataCSV, JSON, XML
OfficeDOCX, XLSX, PPTX
ArchivesZIP

Size Limits

  • Maximum file size: 10 MB
  • Files larger than 10 MB return 413 FILE_TOO_LARGE

Project Files

Project files are uploaded to a project (not a conversation) and provide context for all conversations within that project:

Terminal window
curl -X POST "https://ghostmind.optdmsa.com/v1/projects/$PROJECT_ID/files" \
  -H "Authorization: Bearer $GHOSTMIND_API_KEY" \
  -F "file=@data.csv"

Project file availability depends on the upstream account’s authorization. Check GET /v1/capabilities for project_files → enabled: true before attempting project file uploads.

Next Steps