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

# FanFeed Partner API

> Turn a user's camera roll into an attended-event history.

**Audience:** partner engineering teams.
**Purpose:** everything needed to build a FanFeed-powered "sync your camera roll" tab inside
your own app.

Your users tap **Sync Now** in your app. You read their camera roll, send photo
*metadata* to FanFeed in batches, and FanFeed tells you which live events those photos were
taken at. From that you get an attended-event history and the statistics behind a profile
screen.

You are building the front end. FanFeed is the matching engine behind it.

Five endpoints cover the whole integration:

| # | Endpoint                              | Purpose                                                 |
| - | ------------------------------------- | ------------------------------------------------------- |
| 1 | `POST /users`                         | Create a FanFeed user, once, when your user opts in     |
| 2 | `POST /users/{user_id}/media`         | Send photo metadata in batches; get matched events back |
| 3 | `POST /users/{user_id}/sync-complete` | Tell FanFeed a library scan finished                    |
| 4 | `GET /users/{user_id}/events`         | The user's matched event history                        |
| 5 | `GET /users/{user_id}/stats`          | Profile statistics                                      |

Everything is plain HTTPS request and response. There is nothing to embed, and no SDK you have
to adopt to use the API.

During setup, start with the two operational endpoints rather than these five: `GET /v1/ping`
needs no key and proves the base URL, and `GET /v1/health` confirms which environment your key
is bound to; see [Operational endpoints](/conventions#operational-endpoints).

If the API is not the implementation path you want, we also maintain a **React Native SDK** that
wraps the same flow. It is distributed privately, so ask us and we will get you access.

### How matching works

A photo matches an event when its coordinates fall inside a known venue and its capture time
lands in that event's window, which runs from 2 hours before the start to 4 hours after. A
photo outside every window scores by its distance to the nearest edge and is dropped below a
threshold.

Three consequences worth designing around:

* **A photo without coordinates cannot be matched.** Filter those out before you send them.
* **Most photos will not match.** A camera roll is mostly not taken at live events. A match
  rate in the low single digits is normal and is not a sign of anything wrong.
* **A photo can match a venue without yielding an event.** Some events in FanFeed's catalog
  are not licensed for redistribution and are never returned to partners. When that happens
  the item comes back as unmatched (`matched: false`) with its `venue_id` still set. Treat it
  as any other unmatched photo.

### Concepts

| Term      | Meaning                                                                                                                             |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **User**  | A FanFeed profile, created by you via endpoint 1. Identified by a UUID.                                                             |
| **Media** | One photo or video. You identify it by *your own* asset id; FanFeed stores metadata only and echoes your id back on every response. |
| **Event** | A live event: concert, game, show. Integer id.                                                                                      |
| **Venue** | Where an event happened. Integer id, with coordinates.                                                                              |
| **Match** | The inferred link between a media item and an event.                                                                                |