CoherenceCOHERENCE

File Attachments

Planned API for uploading files and attaching them to records

Planned — not yet available. This page describes a planned capability. The endpoints below do not exist yet and may change before release. Today, files are uploaded and attached to records in the Coherence app — there is no public API for file management yet.

The planned Files API will provide programmatic upload, storage, and attachment of files to records. Files will be stored in workspace-scoped storage and accessed via time-limited signed URLs.

Planned Upload Flow

Uploads will use a direct-to-storage flow so file bytes never proxy through the API:

  1. Request an upload URL — the API will return a presigned URL and a file ID
  2. Upload the file — PUT the file bytes directly to the presigned URL
  3. Confirm — a confirm call will finalize the file record

Endpoint Sketch (design preview)

MethodEndpointPurpose
POST/files/upload-urlGet a presigned upload URL
POST/files/{id}/confirmFinalize the upload
GET/files/{id}Get file metadata
GET/files/{id}/downloadGet a signed download URL
DELETE/files/{id}Delete a file

Example (design preview)

Requesting an upload URL will look like:

curl -X POST "https://api.getcoherence.io/v1/files/upload-url" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "document.pdf",
    "mimeType": "application/pdf",
    "fileSize": 1024000
  }'

and will return a file ID plus a short-lived presigned URL:

{
  "file": {
    "id": "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "uploadUrl": "https://storage.example.com/upload?signature=...",
    "expiresAt": "2026-01-15T11:30:00Z"
  }
}

Attaching Files to Records (planned)

Attachment field values will reference file IDs through the standard record body — the same { displayName, fields } shape the live Records API uses today:

POST /v1/modules/contacts/records
 
{
  "displayName": "John Smith",
  "fields": {
    "profile_photo": "file_b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "documents": [
      "file_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "file_c3d4e5f6-a7b8-9012-cdef-345678901234"
    ]
  }
}

Attachment fields will accept a single file ID (string) or multiple file IDs (array).

Planned Limits and Security

  • File types: images (JPEG, PNG, GIF, WebP, SVG), video (MP4, QuickTime, WebM), and PDF at launch
  • Max size: 50 MB per file
  • Access: all file access via time-limited signed URLs (upload URLs short-lived, download URLs ~1 hour)
  • Scoping: files scoped to your workspace; API keys will only see files in their authorized workspace

Errors

Planned endpoints will use the standard Coherence error envelope (see Error Handling):

{
  "error": {
    "message": "File size exceeds the maximum allowed size of 50 MB",
    "statusCode": 400
  }
}

Related: API Overview | Records API | Authentication