Update Attachment in Knowledge Folder

Replace an existing file in a knowledge folder with a new version

Using our API via a dedicated deployment? Just replace api.odeus.ai with your deployment's base URL: <deployment-url>/api/public

Updates an existing file (attachment) in a knowledge folder by replacing it with a new version. The old file is removed and the new file is processed and embedded.

Requires an API key with the KNOWLEDGE_FOLDER_API scope. The knowledge folder must be shared with the API key. See Share Knowledge Folders with the API for setup instructions.

Request Format

This endpoint accepts multipart/form-data requests with the file attached.

Path Parameters

Parameter	Type	Required	Description
folderId	string	Yes	The ID of the knowledge folder

Form Fields

Field	Type	Required	Description
attachmentId	string	Yes	The ID of the attachment to update
file	file	Yes	The new file to upload (max 256MB)
url	string	No	URL shown to users when this file is used in an answer

Examples

Update with cURL

curl -X PATCH "https://api.odeus.ai/knowledge/{folderId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "attachmentId=att_abc123def456" \
  -F "file=@/path/to/new-document.pdf"

Update with JavaScript

const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

async function updateAttachment(folderId, attachmentId, filePath) {
  const form = new FormData();
  form.append("attachmentId", attachmentId);
  form.append("file", fs.createReadStream(filePath));

  const response = await axios.patch(
    `https://api.odeus.ai/knowledge/${folderId}`,
    form,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        ...form.getHeaders(),
      },
    }
  );

  return response.data;
}

// Example usage
try {
  const result = await updateAttachment(
    "folder_abc123",
    "att_xyz789",
    "/path/to/updated-report.pdf"
  );
  console.log("Attachment updated:", result);
} catch (error) {
  console.error("Failed to update:", error.response?.data?.message);
}

Update with Source URL

const FormData = require("form-data");
const fs = require("fs");
const axios = require("axios");

async function updateAttachmentWithUrl(folderId, attachmentId, filePath, sourceUrl) {
  const form = new FormData();
  form.append("attachmentId", attachmentId);
  form.append("file", fs.createReadStream(filePath));
  form.append("url", sourceUrl);

  const response = await axios.patch(
    `https://api.odeus.ai/knowledge/${folderId}`,
    form,
    {
      headers: {
        Authorization: "Bearer YOUR_API_KEY",
        ...form.getHeaders(),
      },
    }
  );

  return response.data;
}

Response Format

Success Response (200 OK)

{
  status: "success";
  result: {
    id: string;          // Unique attachment ID
    name: string;        // Original filename
    mimeType: string;    // MIME type of the file
    createdAt: string;   // ISO 8601 timestamp
    updatedAt: string;   // ISO 8601 timestamp
    url: string | null;  // Source URL if provided
  };
}

Example Response

{
  "status": "success",
  "result": {
    "id": "att_abc123def456",
    "name": "updated-report.pdf",
    "mimeType": "application/pdf",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-20T14:45:00.000Z",
    "url": null
  }
}

Error Handling

try {
  const response = await updateAttachment(folderId, attachmentId, filePath);
} catch (error) {
  if (error.response) {
    switch (error.response.status) {
      case 400:
        console.error("Invalid request:", error.response.data.message);
        // Possible causes: missing attachmentId, missing file, unsupported file type
        break;
      case 401:
        console.error("Invalid or missing API key");
        break;
      case 403:
        console.error("API key does not have access to this knowledge folder");
        break;
      case 404:
        console.error("Knowledge folder or attachment not found");
        break;
      case 408:
        console.error("Upload request timed out");
        break;
      case 413:
        console.error("File size exceeds 256MB limit");
        break;
      case 429:
        console.error("Rate limit exceeded");
        break;
      case 500:
        console.error("Server error");
        break;
    }
  }
}

Processing Status

After updating, the new file is processed asynchronously. Use the Retrieve Files endpoint to check processing status. The syncStatus field indicates the current state:

• UPLOADING - File is being uploaded
• UPLOADED - File is uploaded and queued for processing
• EXTRACTING - Text is being extracted from the file
• EMBEDDING - Embeddings are being generated
• SYNCED - File is ready for search
• ACTION_FAILED, EXTRACTION_FAILED, EMBEDDING_FAILED, TIMEOUT - Processing failed

Odeus intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

OpenAPI

openapi: 3.0.0
info:
  title: Odeus API
  version: 3.0.0
servers:
  - url: https://api.odeus.ai
security:
  - bearerAuth: []
paths:
  /knowledge/{folderId}:
    patch:
      summary: Update a file in a knowledge folder
      parameters:
        - name: folderId
          in: path
          required: true
          description: The ID of the knowledge folder
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: The new file to upload
                url:
                  type: string
                  description: >-
                    URL that is shown to the user if the file is used in an
                    answer
                attachmentId:
                  type: string
                  description: The ID of the attachment to update
      responses:
        '200':
          description: Attachment updated successfully
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"