Document APIs
The Document APIs enable you to manage document uploads, processing, and retrieval. For detailed information about document processing capabilities, see our Document Processing guide.
Required Headers
All API endpoints require these headers:
- Name
x-connection-id- Type
- string
- Description
Your connection identifier. You can find this in your dashboard under Connections section.
- Name
x-api-key- Type
- string
- Description
Your API key for authentication. You can generate this from your dashboard under API Keys section.
Upload Document Flow
Get Upload URL
Generate a pre-signed URL for uploading a document. This URL will be valid for 10 minutes and allows you to securely upload files to our storage.
Request Body
- Name
fileName- Type
- string
- Description
Name of the file you want to upload
- Name
contentType- Type
- string
- Description
The MIME type of the file (e.g., 'application/pdf', 'image/jpeg')
Request
curl -X POST https://api.usageguard.com/v1/management/documents/upload/presign \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"fileName": "document.pdf",
"contentType": "application/pdf"
}'
Response
{
"url": "https://storage.usageguard.com/presigned-url",
"key": "doc_abc123xyz"
}
400: Bad Request
{
"error": "Bad Request",
"message": "Invalid request. Ensure both fileName and contentType are provided and valid."
}
Finalize Upload
Finalize a document upload and create its metadata record. Call this after successfully uploading a file using the pre-signed URL.
Request Body
- Name
key- Type
- string
- Description
The key received from the pre-sign upload endpoint
- Name
fileName- Type
- string
- Description
Name of the uploaded file
- Name
fileSizeKb- Type
- number
- Description
Size of the file in kilobytes
- Name
fileExtension- Type
- string
- Description
File extension (e.g., 'pdf', 'docx')
- Name
classification- Type
- string
- Description
Document classification level. Defaults to 'confidential'
- Name
tags- Type
- string
- Description
Comma-separated tags for the document
Request
curl -X POST https://api.usageguard.com/v1/management/documents/upload/finalize \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"key": "doc_abc123xyz",
"fileName": "document.pdf",
"fileExtension": "pdf",
"classification": "confidential",
"tags": "contract,legal",
"fileSizeKb": 1024
}'
Response
{
"status": "success",
"message": "Document finalized successfully"
}
400: Bad Request
{
"error": "Bad Request",
"message": "Failed to finalize upload. Invalid file key or missing required fields."
}
List Documents
Retrieve a paginated list of documents in your organization. Use this to browse and search through your document library.
Query Parameters
- Name
status- Type
- string
- Description
Filter documents by processing status
- Name
page- Type
- integer
- Description
Page number for pagination (minimum: 1). Defaults to 1
- Name
pageSize- Type
- integer
- Description
Number of items per page (range: 1-100). Defaults to 10
Request
curl https://api.usageguard.com/v1/management/documents?page=1&pageSize=10 \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}"
Response
{
"items": [
{
"fileName": "document.pdf",
"fileExtension": "pdf",
"classification": "confidential",
"tags": "contract,legal",
"documentIdentifier": "doc_abc123xyz",
"fileSizeKB": 1024,
"processingStatus": "completed",
"createdOnUtc": "2024-03-15T10:30:00Z",
"updatedOnUtc": "2024-03-15T10:35:00Z"
}
],
"page": 1,
"pageSize": 10,
"totalCount": 45,
"totalPages": 5
}
400: Bad Request
{
"error": "Bad Request",
"message": "Invalid request parameters. Ensure page and pageSize are within valid ranges."
}
Document Management
Check Document Status
Check the processing status of one or more documents. Use this to monitor the progress of document processing.
Request Body
- Name
documentIdentifiers- Type
- array
- Description
Array of document identifiers to check status for
Request
curl -X POST https://api.usageguard.com/v1/management/documents/status \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"documentIdentifiers": ["doc_abc123xyz", "doc_def456uvw"]
}'
Response
{
"error": false,
"data": [
{
"documentIdentifier": "doc_abc123xyz",
"processingStatus": "completed",
"lastProcessingError": null
},
{
"documentIdentifier": "doc_def456uvw",
"processingStatus": "processing",
"lastProcessingError": null
}
]
}
400: Bad Request
{
"error": "Bad Request",
"message": "Invalid request. Ensure you've provided at least one document identifier."
}
Update Document Metadata
Update document metadata such as classification and tags. Use this to modify document properties after upload.
Request Body
- Name
key- Type
- string
- Description
Document identifier
- Name
classification- Type
- string
- Description
New classification level for the document
- Name
tags- Type
- string
- Description
Updated comma-separated tags
Request
curl -X PUT https://api.usageguard.com/v1/management/documents \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"key": "doc_abc123xyz",
"classification": "restricted",
"tags": "contract,legal,updated"
}'
Response
{
"status": "success",
"message": "Document metadata updated successfully"
}
400: Bad Request
{
"error": "Bad Request",
"message": "Update failed. Invalid classification value or missing required fields."
}
Delete Document
Delete one or more documents. Warning: This action cannot be undone. Make sure to backup any important documents before deletion.
Request Body
- Name
documentIdentifier- Type
- string
- Description
Identifier of the document to delete
Request
curl -X DELETE https://api.usageguard.com/v1/management/documents \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"documentIdentifier": "doc_abc123xyz"
}'
Response
{
"status": "success",
"message": "Document deleted successfully"
}
400: Bad Request
{
"error": "Bad Request",
"message": "Delete request failed. Document not found or insufficient permissions."
}
Process Document
Initiates or restarts document processing. This endpoint can be used to process documents that are in a failed state or to reprocess documents with updated settings.
Required headers
- Name
Authorization- Type
- string
- Description
Bearer token for authentication
Response
- Name
status- Type
- number
- Description
HTTP 200 on success
Request
curl -X POST https://api.example.com/v1/management/documents/process \
-H "Authorization: Bearer {token}"
Response
200 OK
Get Download URL
Generate a pre-signed URL for downloading a document. This URL will be valid for 5 minutes and provides secure access to download your file.
Request Body
- Name
documentIdentifier- Type
- string
- Description
The unique identifier of the document you want to download
- Name
contentType- Type
- string
- Description
The MIME type of the file
Request
curl -X POST https://api.usageguard.com/v1/management/documents/download/presign \
-H "x-connection-id: {connection_id}" \
-H "x-api-key: {api_key}" \
-H "Content-Type: application/json" \
-d '{
"documentIdentifier": "doc_abc123xyz",
"contentType": "application/pdf"
}'
Response
{
"url": "https://storage.usageguard.com/download-presigned-url",
"key": "doc_abc123xyz"
}
400: Bad Request
{
"error": "Bad Request",
"message": "Invalid request. Verify that the documentIdentifier exists and you have permission to access it."
}