Skip to main content
This page covers the request and response formats used across the Gumnut API.

​
Request Format

​
Headers

All requests should include: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
For file uploads, use multipart/form-data: 
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

​
Request Body

Send JSON payloads for most endpoints: 
{
  "name": "Summer Vacation 2024",
  "description": "Photos from our trip to Hawaii"
}

​
Query Parameters

Use query parameters for filtering, pagination, and opt-in expansions: 
GET /api/assets?limit=50&library_id=lib_123&include=metadata&include=variants

​
Asset expansions with include

Asset responses are intentionally lean by default. Pass include when you need additional fields:
  • metadata for camera, EXIF, GPS, and location fields
  • faces for automatic and manual face boxes
  • people for deduplicated people records
  • metrics for ML-generated quality scores
  • file_data for device IDs, timestamps, checksums, and file size
  • variants for non-thumbnail asset_urls rungs such as small, preview, fullsize, and original
You can repeat include or send a comma-delimited value. For example, include=faces&include=people and include=faces,people are equivalent. When present, each face row includes a source field so you can distinguish automatic detections from manual user-drawn boxes. If your client renders anything larger than the thumbnail rung, start requesting include=variants now. The API reference already marks those larger asset_urls variants as opt-in, so sending the token keeps your integration aligned with the lean response model.

​
Response Format

​
Successful Responses

Successful requests return JSON with appropriate HTTP status codes: 
{
  "id": "asset_abc123",
  "mime_type": "image/jpeg",
  "original_file_name": "photo.jpg",
  "local_datetime": "2024-07-15T12:00:00",
  "created_at": "2024-07-15T19:04:12Z",
  "asset_urls": {
    "thumbnail": {
      "url": "...",
      "mimetype": "image/webp"
    }
  },
  "metadata": null,
  "faces": null,
  "people": null
}
Expanded fields stay null or absent until you request them with include.

​
Asset timestamp fields

Gumnut uses different timestamps for different jobs:
  • local_datetime is the capture time in the device’s local wall-clock time.
  • If Gumnut knows the capture offset, local_datetime includes it, for example 2024-07-15T12:00:00-07:00.
  • If the source only records a wall-clock capture time and not its offset, local_datetime is returned without a timezone suffix, for example 2024-07-15T12:00:00.
  • created_at is when Gumnut created the asset record. It is not the capture time.
  • file_data.file_created_at and file_data.file_modified_at describe the uploaded file on the source device. Request them with include=file_data when you need file-level timestamps.
{
  "local_datetime": "2024-07-15T12:00:00",
  "created_at": "2024-07-15T19:04:12Z",
  "file_data": {
    "file_created_at": "2024-07-15T12:03:44-07:00",
    "file_modified_at": "2024-07-15T12:05:10-07:00"
  }
}
Use local_datetime when you want to group or filter by when an asset was captured. Use created_at when you need to track when the asset record arrived in Gumnut. Status codes:
  • 200 OK - Request succeeded
  • 201 Created - Resource created
  • 204 No Content - Request succeeded with no content

​
Error Responses

Errors return a consistent JSON structure: 
{
  "error": {
    "code": "validation_error",
    "message": "Invalid request parameters",
    "details": {
      "field": "album_name",
      "issue": "Required field missing"
    }
  }
}
Status codes:
  • 400 Bad Request - Invalid request
  • 401 Unauthorized - Authentication required
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded (see Rate Limiting)
  • 500 Internal Server Error - Server error

​
Best Practices

​
Error Handling

  • Implement exponential backoff for retries on 429 and 5xx errors
  • Handle rate limits gracefully using the Retry-After header (see Rate Limiting)
  • Log errors with the request ID for debugging
  • Validate input before sending requests

​
Security

  • Never expose API keys in client-side code
  • Use HTTPS for all requests
  • Implement proper authentication flows