Endpoint Overview
HTTP Method
DELETE
Endpoint URL
Authentication
This endpoint requires authentication using an API token. You must include your API token as a Bearer token in the Authorization header.Learn how to create and manage API tokens in the API Tokens guide.
Request Format
Headers
Header | Value | Required |
---|---|---|
Authorization | Bearer YOUR_API_TOKEN | ✅ Yes |
Content-Type | application/json | ✅ Yes |
Request Body
The request must be sent as JSON with the following field:Field | Type | Description | Required |
---|---|---|---|
file_name | string | Name of the file to delete (case-sensitive) | ✅ Yes |
Important Considerations
Permanent Deletion
Permanent Deletion
Warning: This operation is irreversible
- All document content and metadata will be permanently removed
- Associated partition nodes and embeddings will be deleted
- Flows using this document will be automatically updated
- No backup or recovery options are available
File Name Requirements
File Name Requirements
Exact match required
- File names are case-sensitive
- Must match the exact name from upload or list endpoints
- Include the full filename with extension
- Use the List Sources endpoint to verify file names
Flow Impact
Flow Impact
Automatic flow updates
- Dataset nodes using this document will be updated automatically
- Successor nodes in affected flows will be marked as outdated
- Flow execution may be impacted until nodes are reconfigured
- Multiple flows can be affected by a single deletion
Request Example
Response Format
Success Response (200 OK)
Response Fields
Field | Type | Description |
---|---|---|
status | string | Deletion result (typically “success”) |
message | string | Human-readable confirmation message |
file_name | string | Name of the deleted file |
project_id | string | UUID of the project the file was removed from |
project_name | string | Name of the project |
Code Examples
JavaScript/Node.js
Python
cURL
PHP
Error Responses
Common Error Codes
Status Code | Error Type | Description |
---|---|---|
400 | Bad Request | Invalid request format or missing file name |
401 | Unauthorized | Invalid or missing API token |
403 | Forbidden | Access denied to the specified project |
404 | Not Found | File not found in the project |
500 | Internal Server Error | Server-side error during deletion |
Error Response Format
Error Examples
File Not Found (404)
File Not Found (404)
- Verify the exact file name (case-sensitive)
- Use the List Sources endpoint to check available files
- Ensure the file wasn’t already deleted
Invalid API Token (401)
Invalid API Token (401)
- Check your API token format (should start with “grlm_”)
- Verify the token hasn’t been revoked in the dashboard
- Ensure correct Authorization header format
Access Denied (403)
Access Denied (403)
- Verify you’re using the correct API token for this project
- Check that you have delete permissions
- Contact your project administrator
Invalid Request (400)
Invalid Request (400)
- Ensure
file_name
field is included in JSON body - Verify the file name is not empty
- Check JSON format is valid
Best Practices
Pre-Deletion Verification
Always verify before deletion
Always verify before deletion
Check for active processing
Check for active processing
Before deleting documents that are currently processing:
- Wait for processing to complete when possible
- Processing documents may be in an inconsistent state
- Consider the impact on any dependent workflows
- Monitor processing status using the List Sources endpoint
Review flow dependencies
Review flow dependencies
Before deletion, consider:
- Which flows use this document
- Impact on downstream processing
- Whether alternative documents can serve the same purpose
- Need to reconfigure affected flows after deletion
Safety Measures
- Implement confirmation prompts in interactive applications
- Log all deletion operations for audit trails
- Use descriptive variable names to avoid accidental deletions
- Test with non-production data when implementing deletion features
- Consider soft deletion patterns for critical applications
Error Handling
- Implement retry logic for transient network errors (not for 404/403 errors)
- Validate file names before making deletion requests
- Handle batch operations carefully to avoid partial failures
- Provide clear error messages to end users
Integration Examples
Batch Deletion with Safety Checks
Project Cleanup Tool
File Lifecycle Management
Troubleshooting
File not found errors
File not found errors
Causes: File doesn’t exist, wrong name, or already deletedSolutions:
- Use List Sources to verify exact file names
- Check for case sensitivity (file names are case-sensitive)
- Verify you’re using the correct project/API token
- Consider that the file may have been deleted by another process
Authentication failures
Authentication failures
Causes: Invalid token, token revoked, or wrong project accessSolutions:
- Verify API token format (should start with “grlm_”)
- Check token status in the GraphorLM dashboard
- Ensure token has delete permissions for the project
- Try regenerating the API token if needed
Deletion timeouts
Deletion timeouts
Causes: Large files, complex cleanup operations, or server loadSolutions:
- Increase request timeout (60+ seconds recommended)
- Retry the operation after a short delay
- Contact support for persistent timeout issues
- Consider deleting files during off-peak hours
Flow synchronization issues
Flow synchronization issues
Causes: Flows updating asynchronously after deletionSolutions:
- Allow time for flow updates to propagate
- Refresh flow data in your application
- Reconfigure affected flows manually if needed
- Monitor flow status after bulk deletions
Network connectivity
Network connectivity
Causes: DNS issues, firewall restrictions, or network timeoutsSolutions:
- Test connectivity to sources.graphorlm.com
- Check firewall allows outbound HTTPS traffic
- Verify DNS resolution is working
- Try from a different network if issues persist