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

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

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.

# 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

Category	Types
Documents	PDF, TXT, Markdown
Images	PNG, JPEG, GIF, WebP
Code	Python, JavaScript, TypeScript, etc.
Data	CSV, JSON, XML
Office	DOCX, XLSX, PPTX
Archives	ZIP

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:

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

• Chat Completions — API reference
• Assets — Generated asset handling
• Attachments Guide — User guide
• Errors — Error codes including file errors