Skip to main content

​
Quickstart Guide

This guide will walk you through getting started with Gumnut, from creating your account to uploading and querying your first assets.

​
Prerequisites

  • A Gumnut account (sign up at www.gumnut.ai/waitlist if you don’t have one)
  • Basic familiarity with REST APIs
  • (Optional) Node.js or Python installed for SDK usage

​
Step 1: Create Your Account

If you don’t already have an account, sign up for the waitlist at www.gumnut.ai/waitlist. Once approved, you’ll receive an invitation to create your account.

​
Step 2: Get Your API Key

  1. Log into the Gumnut Dashboard
  2. Navigate to API Keys in the sidebar
  3. Click Create API Key
  4. Give your key a descriptive name (e.g., “Development”, “Production”)
  5. Copy and securely store your API key
Your API key is shown only once. Store it securely and never commit it to version control.
See the Authentication page for more information about how requests are authenticated.

​
Step 3: Query Your Libraries

By default, you’ll have one library created for you. Let’s query it using the API: 
curl -X GET https://api.gumnut.ai/api/libraries \
  -H "Authorization: Bearer YOUR_API_KEY"
You should see a response with your default library: 
{
  "libraries": [
    {
      "id": "lib_...",
      "name": "Default Library",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

​
Step 4: Upload Your First Asset

Now let’s upload a photo to your library: 
curl -X POST https://api.gumnut.ai/api/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "asset_data=@/path/to/your/photo.jpg" \
  -F "device_asset_id=unique_id_123" \
  -F "device_id=my_device" \
  -F "file_created_at=2024-01-01T00:00:00Z" \
  -F "file_modified_at=2024-01-01T00:00:00Z"
Gumnut will asynchronously process your upload to:
  • Generate embeddings for semantic search
  • Extract EXIF metadata
  • Detect faces and group them into people
  • Create optimized thumbnails
You can view your assets immediately through the dashboard while processing happens in the background.

​
Step 5: Query Your Assets

After uploading, you can query your assets: 
curl -X GET https://api.gumnut.ai/api/assets \
  -H "Authorization: Bearer YOUR_API_KEY"
The response will include your uploaded asset with extracted metadata: 
{
  "assets": [
    {
      "id": "asset_...",
      "device_asset_id": "unique_id_123",
      "type": "IMAGE",
      "original_path": "...",
      "exif_info": {
        "make": "Apple",
        "model": "iPhone 15 Pro",
        "date_time_original": "2024-01-01T00:00:00Z"
      },
      "faces": [...],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
Faces, embeddings for search, and some metrics might not be populated immediately as they’re processed asynchronously.

​
Step 6: Create an Album

Let’s organize your asset into an album: 
curl -X POST https://api.gumnut.ai/api/albums \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "album_name": "My First Album",
    "description": "Testing Gumnut API"
  }'

​
Step 7: Add Asset to Album

Finally, add your uploaded asset to the album: 
curl -X POST https://api.gumnut.ai/api/albums/{album_id}/assets \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_ids": ["asset_..."]
  }'

​
Next Steps

Congratulations! You’ve successfully:
  • Created an API key
  • Uploaded an asset
  • Created an album
  • Organized your content
Now you can:
  • Explore the full API Reference tab for documentation and an interactive console for all available endpoints
  • Install our SDKs for easier integration
  • Set up the MCP server for AI tool integration
  • Learn about authentication options including OAuth
⌘I