Skip to main content

​
API Overview

Gumnut provides a comprehensive REST API that gives you full programmatic access to all platform features. The API follows RESTful principles and supports the OpenAPI specification.

​
Base URL

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

​
OpenAPI Specification

Gumnut publishes an OpenAPI 3.0 specification that you can use to generate client libraries, import into API testing tools like Postman, or create mock servers: Specification URL: https://api.gumnut.ai/openapi.json

​
API Resources

The API provides access to the following resources:
  • Assets — Upload, list, query, update, and delete photos and videos
  • Albums — Create and manage photo collections
  • Libraries — Manage separate photo libraries
  • People & Faces — AI-powered facial recognition and grouping
  • Search — Semantic search using natural language, plus metadata filtering
  • API Keys — Manage authentication keys programmatically
See the API Reference tab for the full list of endpoints and interactive documentation.

​
Getting Started

Follow these steps to make your first API calls.

​
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

​
Get Your API Key

Follow the steps on the API Keys page to create and configure your key.

​
Query Your Libraries

By default, you’ll have one library created for you. Let’s query it: 
curl -X GET https://api.gumnut.ai/api/libraries \
  -H "Authorization: Bearer YOUR_API_KEY"

[
  {
    "id": "lib_...",
    "name": "Default Library",
    "created_at": "2025-01-01T00:00:00Z"
  }
]

​
Upload Your First Asset

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 create optimized thumbnails. You can view your assets immediately while processing happens in the background.

​
Query Your Assets

curl -X GET https://api.gumnut.ai/api/assets \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": [
    {
      "id": "asset_...",
      "device_asset_id": "unique_id_123",
      "mime_type": "image/jpeg",
      "original_file_name": "photo.jpg",
      "exif": {
        "make": "Apple",
        "model": "iPhone 15 Pro"
      },
      "thumbnail_url": "...",
      "download_url": "...",
      "faces": [...],
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "has_more": false
}
Faces, embeddings for search, and some metrics might not be populated immediately as they’re processed asynchronously.

​
Create an Album

curl -X POST https://api.gumnut.ai/api/albums \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Album",
    "description": "Testing Gumnut API"
  }'

​
Add Asset to 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