Nookhive Logo
StyleguideAPI Reference

Files API

Upload and manage files, images, and documents through the NookHive API.

Overview

The Files API allows you to upload and manage files within your organization. This includes images for events, documents for invoices, and other assets.

Files are uploaded using pre-signed URLs for security and performance. All uploaded files are scanned for malware before being made available.

Base Path

https://api.nookhive.com/v1/files

⚠️ File Limits

  • Maximum file size: 10 MB
  • Allowed types: Images (JPG, PNG, GIF, WebP), Documents (PDF), Data (CSV, JSON)
  • Upload URL expiration: 15 minutes
  • Download URL expiration: 1 hour

Endpoints

POST/v1/files/upload-url

Get Upload URL

Generate a pre-signed URL for uploading a file. The URL is valid for 15 minutes.

Parameters

NameTypeDescription
filename*stringOriginal filename with extension
contentType*stringMIME type (e.g., image/jpeg, application/pdf)
purposestringFile purpose: EVENT_COVER, ORGANIZATION_LOGO, INVOICE, ATTACHMENT
Example RequestBASH
curl -X POST "https://api.nookhive.com/v1/files/upload-url" \
  -H "Authorization: Bearer nk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "event-cover.jpg",
    "contentType": "image/jpeg",
    "purpose": "EVENT_COVER"
  }'
ResponseJSON
{
  "uploadUrl": "https://storage.nookhive.com/upload/...",
  "fileId": "file_abc123",
  "expiresAt": "2026-01-15T10:15:00Z",
  "headers": {
    "Content-Type": "image/jpeg",
    "x-amz-acl": "private"
  }
}
PUT(upload URL)

Upload File

Upload the file directly to the pre-signed URL. Use the headers provided in the upload-url response.

Example UploadBASH
curl -X PUT "https://storage.nookhive.com/upload/..." \
  -H "Content-Type: image/jpeg" \
  -H "x-amz-acl: private" \
  --data-binary @event-cover.jpg
GET/v1/files/{id}

Get File Details

Retrieve metadata about an uploaded file.

Parameters

NameTypeDescription
id*stringFile ID
Example RequestBASH
curl -X GET "https://api.nookhive.com/v1/files/file_abc123" \
  -H "Authorization: Bearer nk_live_your_api_key_here"
ResponseJSON
{
  "file": {
    "id": "file_abc123",
    "filename": "event-cover.jpg",
    "contentType": "image/jpeg",
    "size": 245678,
    "purpose": "EVENT_COVER",
    "status": "READY",
    "scanStatus": "CLEAN",
    "url": "https://files.nookhive.com/file_abc123/event-cover.jpg",
    "createdAt": "2026-01-15T10:00:00Z"
  }
}
GET/v1/files/{id}/download-url

Get Download URL

Generate a temporary download URL for a file. Valid for 1 hour.

Parameters

NameTypeDescription
id*stringFile ID
Example RequestBASH
curl -X GET "https://api.nookhive.com/v1/files/file_abc123/download-url" \
  -H "Authorization: Bearer nk_live_your_api_key_here"
ResponseJSON
{
  "downloadUrl": "https://files.nookhive.com/download/...",
  "expiresAt": "2026-01-15T11:00:00Z"
}
DELETE/v1/files/{id}

Delete File

Delete an uploaded file. This action cannot be undone.

Parameters

NameTypeDescription
id*stringFile ID
Example RequestBASH
curl -X DELETE "https://api.nookhive.com/v1/files/file_abc123" \
  -H "Authorization: Bearer nk_live_your_api_key_here"

The File Object

{
  "id": "file_abc123",
  "filename": "event-cover.jpg",
  "contentType": "image/jpeg",
  "size": 245678,
  "purpose": "EVENT_COVER",
  "associatedWith": {
    "type": "EVENT",
    "id": "evt_example123"
  },
  "status": "READY",
  "scanStatus": "CLEAN",
  "scanCompletedAt": "2026-01-15T10:01:00Z",
  "url": "https://files.nookhive.com/file_abc123/event-cover.jpg",
  "thumbnails": {
    "small": "https://files.nookhive.com/file_abc123/thumb-sm.jpg",
    "medium": "https://files.nookhive.com/file_abc123/thumb-md.jpg",
    "large": "https://files.nookhive.com/file_abc123/thumb-lg.jpg"
  },
  "uploadedBy": "user_xyz789",
  "createdAt": "2026-01-15T10:00:00Z"
}

Upload Flow

  1. Request upload URL - Call POST /files/upload-url with file details
  2. Upload file - PUT the file binary to the returned uploadUrl
  3. Wait for processing - File is scanned for malware (usually < 10 seconds)
  4. Use the file - Once status is READY, use the file URL