Skip to main content

​
API Overview

Gumnut provides a comprehensive REST API that gives you full programmatic access to all platform features. Our API follows RESTful principles and supports the OpenAPI specification, making it easy to integrate with any language or framework.

​
OpenAPI Specification

Gumnut supports the OpenAPI 3.0 specification, providing machine-readable API documentation that can be used to:
  • Generate client libraries automatically
  • Import into API testing tools like Postman or Insomnia
  • Create mock servers for testing
  • Generate comprehensive documentation
Latest OpenAPI Specification: https://api.gumnut.ai/openapi.json

​
Base URL

All API requests should be made to: 
https://api.gumnut.ai

​
API Resources

The Gumnut API provides access to the following resources:

​
Assets

Manage photos and videos in your library:
  • Upload new assets with metadata
  • Query and filter your asset collection
  • Update asset information
  • Delete unwanted assets
  • Generate and retrieve thumbnails
Key endpoints:
  • POST /api/assets - Upload a new asset
  • GET /api/assets - List assets with filtering
  • GET /api/assets/{id} - Get specific asset details
  • PATCH /api/assets/{id} - Update asset details
  • DELETE /api/assets/{id} - Delete an asset

​
Albums

Organize your assets into collections:
  • Create and manage albums
  • Add or remove assets from albums
  • Share albums (coming soon)
  • Set album covers and descriptions
Key endpoints:
  • POST /api/albums - Create a new album
  • GET /api/albums - List all albums
  • PATCH /api/albums/{id} - Update album metadata
  • DELETE /api/albums/{id} - Delete an album
  • POST /api/albums/{id}/assets - Add assets to album

​
Libraries

Manage separate photo libraries:
  • Create multiple libraries for organization
  • Set library-specific settings
  • Control access permissions
Key endpoints:
  • GET /api/libraries - List user libraries
  • POST /api/libraries - Create a new library
  • PATCH /api/libraries/{id} - Update library settings

​
People & Faces

AI-powered facial recognition and grouping:
  • Automatic face detection in photos
  • Group similar faces into people
  • Name and manage recognized people
  • Search assets by people
Key endpoints:
  • GET /api/people - List recognized people
  • POST /api/people - Create a person record
  • GET /api/faces - Get detected faces
Powerful search capabilities:
  • Semantic search using natural language
  • Filter by metadata (date, location, camera)
  • Search by detected objects and scenes
  • Find similar images
Key endpoints:
  • POST /api/search/assets - Search for assets
  • POST /api/search/albums - Search for albums
  • POST /api/search/people - Search for people

​
API Keys

Manage authentication:
  • Create and revoke API keys
  • Set permissions and scopes
Key endpoints:
  • GET /api-keys/ - List API keys
  • POST /api-keys/ - Create new API key
  • DELETE /api-keys/{id} - Revoke API key

​
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: 
{
  "album_name": "Summer Vacation 2024",
  "description": "Photos from our trip to Hawaii"
}

​
Query Parameters

Use query parameters for filtering and pagination: 
GET /api/assets?limit=50&offset=100&order_by=created_at

​
Response Format

​
Successful Responses

Successful requests return JSON with appropriate HTTP status codes: 
{
  "id": "asset_abc123",
  "type": "IMAGE",
  "original_path": "/storage/assets/abc123.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "exif_info": {
    "make": "Apple",
    "model": "iPhone 15 Pro"
  }
}
Status codes:
  • 200 OK - Request succeeded
  • 201 Created - Resource created
  • 204 No Content - Request succeeded with no content

​
Error Responses

Errors return 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
  • 500 Internal Server Error - Server error

​
Pagination

List endpoints support pagination using limit and offset: 
# Get first 50 assets
GET /api/assets?limit=50

# Get next 50 assets
GET /api/assets?limit=50&offset=50
Paginated responses include metadata: 
{
  "data": [...],
  "pagination": {
    "total": 500,
    "limit": 50,
    "offset": 0,
    "has_next": true
  }
}

​
Rate Limiting

API requests are rate limited to ensure fair usage:
  • Default limit: 1000 requests per hour
  • Burst limit: 100 requests per minute
  • Upload limit: 100 uploads per hour
Rate limit information is included in response headers: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1642255200
When rate limited, you’ll receive a 429 response: 
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests",
    "retry_after": 60
  }
}

​
Filtering & Sorting

Most list endpoints support filtering and sorting:

​
Filtering

Use query parameters to filter results: 
# Filter by date range
GET /api/assets?created_after=2024-01-01&created_before=2024-02-01

# Filter by type
GET /api/assets?type=IMAGE

# Multiple filters
GET /api/assets?type=IMAGE&has_faces=true&library_id=lib_123

​
Sorting

Control result ordering with order_by: 
# Sort by creation date (newest first)
GET /api/assets?order_by=-created_at

# Sort by name (alphabetical)
GET /api/albums?order_by=name

# Multiple sort fields
GET /api/assets?order_by=-created_at,name

​
Webhooks

Get real-time updates about events in your account. See the Webhooks documentation for details.

​
Versioning

The API does not currently support versioning.

​
Best Practices

​
Efficiency

  • Use batch operations when available
  • Cache responses when appropriate
  • Implement pagination for large datasets
  • Use webhooks instead of polling

​
Error Handling

  • Implement exponential backoff for retries
  • Handle rate limits gracefully
  • Log errors for debugging
  • Validate input before sending requests

​
Security

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

​
Support

Need help with the API? The Gumnut API is designed to be powerful yet simple to use. Start building amazing photo applications today!
⌘I