The 415 Unsupported Media Type error you’re encountering is a common issue when working with Agile’s document upload API. The problem stems from misunderstanding how the API handles file uploads versus metadata. Here’s a comprehensive solution addressing all three critical aspects:
MIME Type Handling:
Agile’s document API validates MIME types at two levels - the HTTP request Content-Type and the individual file part Content-Type in multipart uploads. Your original approach of setting Content-Type: application/pdf at the request level is incorrect for file uploads. The request-level Content-Type must be multipart/form-data with a boundary parameter. The PDF MIME type is specified within the multipart section for the file part itself.
Additionally, verify that application/pdf is registered in Agile’s allowed MIME types. This is configured server-side in Admin > Server Settings > File Manager. If PDF isn’t in the whitelist, the API will reject it regardless of correct formatting.
Multipart Form Data:
The file upload endpoint requires properly structured multipart/form-data encoding. Here’s the correct format:
POST /api/v1/documents/{docId}/files
Content-Type: multipart/form-data; boundary=----Boundary123
------Boundary123
Content-Disposition: form-data; name="file"; filename="document.pdf"
Content-Type: application/pdf
[PDF binary content here]
------Boundary123--
The field name MUST be ‘file’ (lowercase). The filename parameter in Content-Disposition should include the .pdf extension, which Agile uses to validate against the declared Content-Type. The boundary string must be unique and match between the Content-Type header and the body delimiters.
File Upload API:
The document creation and file attachment are two separate API operations:
- First, create the document object (POST /api/v1/documents) with metadata
- Then, attach the file using the document ID (POST /api/v1/documents/{docId}/files)
Don’t resend metadata in the file upload request - it’s already associated with the document ID. The file upload endpoint only expects the file part in the multipart form.
Common Implementation Issues:
- Missing or incorrect boundary parameter in Content-Type header
- Using ‘attachment’ or ‘document’ instead of ‘file’ as the field name
- File extension mismatch with Content-Type (e.g., .doc file with application/pdf type)
- Not including filename in Content-Disposition header
- Attempting to upload file and metadata in a single request
Testing Approach:
Use a tool like Postman or curl to verify your multipart structure before implementing in code. Most HTTP libraries have multipart helpers that handle boundary generation and formatting automatically - use those instead of manually constructing the multipart body. In Java, use Apache HttpClient’s MultipartEntityBuilder. In Python, use the ‘files’ parameter in requests library.
Once you switch to proper multipart/form-data encoding with the correct field name and MIME type configuration, your PDF uploads should work reliably.
This draft is based on general Oracle Agile PLM knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.