Attachment Signed URL Service - API Contract

GET /api/v1/attachment-signed-urls/api/v1/attachment-signed-urls

List currently cached signed URLs for a set of storage paths.

Public

Response Example

{
  "data": [
    {
      "storage_path": "org_abc123/activities/act_4b2e1f89/session_notes.pdf",
      "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_4b2e1f89/session_notes.pdf?token=eyJhb...",
      "expires_at": "2026-03-26T16:23:45Z",
      "cached": true
    },
    {
      "storage_path": "org_abc123/activities/act_4b2e1f89/progress_photo.jpg",
      "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_4b2e1f89/progress_photo.jpg?token=eyJhb...",
      "expires_at": "2026-03-26T16:23:45Z",
      "cached": true
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

GET /api/v1/attachment-signed-urls/api/v1/attachment-signed-urls/:id

Get a fresh signed URL for a single attachment by attachment ID. Calls getSignedUrl(storagePath, expiresInSeconds).

Public

Response Example

{
  "attachment_id": "att_7f3a9c12",
  "storage_path": "org_abc123/activities/act_4b2e1f89/session_notes.pdf",
  "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_4b2e1f89/session_notes.pdf?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in_seconds": 3600,
  "expires_at": "2026-03-26T15:23:45Z",
  "cached": false
}

POST /api/v1/attachment-signed-urls/api/v1/attachment-signed-urls

Prefetch and cache signed URLs for multiple storage paths. Calls prefetchUrls(storagePaths).

Public

Request Example

{
  "storage_paths": [
    "org_abc123/activities/act_4b2e1f89/session_notes.pdf",
    "org_abc123/activities/act_4b2e1f89/progress_photo.jpg",
    "org_abc123/activities/act_9a1c7b34/intake_form.pdf"
  ],
  "expires_in_seconds": 7200
}

Response Example

{
  "prefetched": 3,
  "results": [
    {
      "storage_path": "org_abc123/activities/act_4b2e1f89/session_notes.pdf",
      "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_4b2e1f89/session_notes.pdf?token=eyJhb...",
      "expires_at": "2026-03-26T16:23:45Z",
      "cached": true
    },
    {
      "storage_path": "org_abc123/activities/act_4b2e1f89/progress_photo.jpg",
      "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_4b2e1f89/progress_photo.jpg?token=eyJhb...",
      "expires_at": "2026-03-26T16:23:45Z",
      "cached": true
    },
    {
      "storage_path": "org_abc123/activities/act_9a1c7b34/intake_form.pdf",
      "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_9a1c7b34/intake_form.pdf?token=eyJhb...",
      "expires_at": "2026-03-26T16:23:45Z",
      "cached": true
    }
  ]
}

PUT /api/v1/attachment-signed-urls/api/v1/attachment-signed-urls/:id

Refresh (extend) the signed URL for an attachment, invalidating the old cached entry.

Public

Request Example

{
  "expires_in_seconds": 14400
}

Response Example

{
  "attachment_id": "att_7f3a9c12",
  "storage_path": "org_abc123/activities/act_4b2e1f89/session_notes.pdf",
  "signed_url": "https://xyz.supabase.co/storage/v1/object/sign/attachments/org_abc123/activities/act_4b2e1f89/session_notes.pdf?token=eyNewToken...",
  "expires_in_seconds": 14400,
  "expires_at": "2026-03-26T18:23:45Z",
  "cached": true,
  "previous_url_invalidated": true
}

DELETE /api/v1/attachment-signed-urls/api/v1/attachment-signed-urls/:id

Invalidate the cached signed URL for a specific attachment. Calls invalidateCache(storagePath).

Public

Response Example

{
  "success": true,
  "storage_path": "org_abc123/activities/act_4b2e1f89/session_notes.pdf",
  "cache_cleared": true
}

DELETE /api/v1/attachment-signed-urls/api/v1/attachment-signed-urls

Clear all cached signed URLs. Calls clearAllCache(). Admin-only operation.

Public

Response Example

{
  "success": true,
  "entries_cleared": 47
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}