Skip to main content

​
Requests & Responses

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 and pagination: 
GET /api/assets?limit=50&library_id=lib_123

​
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",
  "thumbnail_url": "...",
  "download_url": "...",
  "created_at": "2024-01-15T10:30:00Z",
  "exif": {
    "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 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