Files (Workflow)

The Files API lets you upload files, retrieve metadata, and request signed URLs that can be used directly in browsers.

Base Endpoint

All file endpoints are located at:

/tenant/{tenantId}/v1/Files

Authentication Requirements

File operations require authenticated access for the tenant. In browser and user-facing integrations, use a bearer token:

Authorization: Bearer {token}

If your tenant uses workspace-aware access control, make sure the token presented to the API is valid for the workspace that should access the file.

Uploading a File

Use POST /tenant/{tenantId}/v1/Files with multipart/form-data.

Form fields:

• file – Required file payload
• workflowItemId – Optional workflow item association
• workflowDefinitionId – Optional workflow definition association

const formData = new FormData();
formData.append('file', selectedFile);
formData.append('workflowItemId', workflowItemId);
formData.append('workflowDefinitionId', workflowDefinitionId);

const response = await fetch(
  `https://workflow.agglestone.com/tenant/${tenantId}/v1/Files`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    },
    body: formData
  }
);

const metadata = await response.json();

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tenantId": "your-tenant-id",
  "workspaceId": "workspace-id",
  "fileName": "report.pdf",
  "contentType": "application/pdf",
  "fileSize": 123456,
  "blobPath": "tenant-id/workspace-id/file-id/report.pdf",
  "downloadUrl": "/tenant/your-tenant-id/v1/Files/550e8400-e29b-41d4-a716-446655440000/signed-url",
  "createdAt": "2026-04-02T10:30:00Z",
  "workflowItemId": "workflow-item-id",
  "workflowDefinitionId": "sample-registration"
}

Getting File Metadata

Use GET /tenant/{tenantId}/v1/Files/{fileId}/metadata to retrieve metadata without requesting a signed URL.

GET /tenant/{tenantId}/v1/Files/{fileId}/metadata
Authorization: Bearer {token}

Getting a Signed URL

Use GET /tenant/{tenantId}/v1/Files/{fileId}/signed-url to retrieve a short-lived signed URL.

const response = await fetch(
  `https://workflow.agglestone.com/tenant/${tenantId}/v1/Files/${fileId}/signed-url`,
  {
    headers: {
      'Authorization': `Bearer ${token}`
    }
  }
);

const { signedUrl } = await response.json();

{
  "signedUrl": "https://storage.agglestone.com/container/path/file.pdf?sig=..."
}

The signed URL can then be used directly in a browser without adding API authentication headers.

<img src="https://storage.agglestone.com/container/path/file.jpg?sig=..." alt="Uploaded file" />

Deleting a File

Use DELETE /tenant/{tenantId}/v1/Files/{fileId} to remove a file.

DELETE /tenant/{tenantId}/v1/Files/{fileId}
Authorization: Bearer {token}

Successful deletion returns 204 No Content.

Typical Status Codes

• 201 Created when a file is uploaded successfully
• 200 OK when metadata or a signed URL is returned
• 400 Bad Request when the file is missing or invalid
• 401 Unauthorized when authentication is missing or invalid
• 403 Forbidden when the caller is not allowed to access the file
• 404 Not Found when the file does not exist
• 413 Payload Too Large when the uploaded file exceeds the allowed size

Frontend Integration Notes

• Let the browser set the Content-Type header for multipart/form-data
• Store the returned file ID if you want to reference the file later from workflow or managed data records
• Refresh signed URLs when needed because they are short-lived by design

📚 API Documentation: For exact schemas and response details, visit https://workflow.agglestone.com/swagger.