Skip to main content
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 people grouping, face review, and manual face boxes for missed detections
  • 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 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_...",
      "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
    }
  ],
  "has_more": false
}
Asset responses are lean by default. When you need richer fields such as metadata, faces, people, file_data, or non-thumbnail asset_urls, pass the relevant include values. In particular, clients that render small, preview, fullsize, or original variants should request include=variants.Capture timestamps can be timezone-aware or offsetless depending on the source metadata. See Requests & Responses for how local_datetime, created_at, and file_data.file_created_at differ.

​
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