> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> Get started with the Gumnut REST API — explore resources and make your first API calls

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:

```text theme={null}
https://api.gumnut.ai
```

## OpenAPI Specification

Gumnut publishes an OpenAPI 3.1 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](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
* **Stacks** — Group burst sequences and related shots, automatically or by hand
* **Events** — Read a log of changes in your library
* **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 [app.gumnut.ai/sign-up](https://app.gumnut.ai/sign-up) if you don't have one)
* Basic familiarity with REST APIs
* (Optional) Node.js or Python installed for [SDK](../sdks/overview) usage

### Get Your API Key

Follow the steps on the [API Keys](../authentication/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:

```bash theme={null}
curl -X GET https://api.gumnut.ai/api/libraries \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

### Upload Your First Asset

```bash theme={null}
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"
```

<Note>
  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.
</Note>

### Query Your Assets

```bash theme={null}
curl -X GET https://api.gumnut.ai/api/assets \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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
}
```

<Note>
  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](./requests-and-responses#asset-timestamp-fields) for how `local_datetime`, `created_at`, and `file_data.file_created_at` differ.
</Note>

### Create an Album

```bash theme={null}
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

```bash theme={null}
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

* Explore the full **API Reference** tab for interactive documentation of all endpoints
* Install our [SDKs](../sdks/overview) for easier integration with TypeScript or Python
* Set up the [MCP server](../mcp/overview) for AI tool integration
* Learn how to work with [people and faces](./faces-and-people), [request formats](./requests-and-responses), [pagination](./pagination-and-filtering), and [rate limits](./rate-limiting)
* Review [authentication options](../authentication/overview) including OAuth