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

# Tags

> Organizing content with tags

## Overview

Tags help categorize and discover content on FoN. Users can add tags when uploading or update them later.

## Adding Tags

### During Upload

Include tags as a comma-separated string:

```bash theme={null}
curl -X POST https://fucksornot.com/api/v1/upload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "upload_type=image" \
  -F "description=New gadget" \
  -F "tags=gadget,tech,electronics" \
  -F "file=@image.jpg"
```

### After Upload

Add tags to an existing upload:

```bash theme={null}
curl -X POST https://fucksornot.com/api/uploads/UPLOAD_ID/tags \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["new-tag", "another-tag"]}'
```

## Tag Properties

| Property       | Type    | Description                     |
| -------------- | ------- | ------------------------------- |
| `id`           | UUID    | Unique identifier               |
| `name`         | string  | Display name                    |
| `slug`         | string  | URL-friendly version            |
| `upload_count` | integer | Number of uploads with this tag |

## Tag Limits

* Maximum **10 tags** per upload
* Tag names must be between **2 and 50 characters**
* Tag names can only contain letters, numbers, spaces, and hyphens — tags with other characters are rejected with a `400` error rather than being stripped
* Tag names are trimmed, but their case is preserved; only the generated `slug` is lowercased

## Listing Tags

Get all tags with upload counts:

```bash theme={null}
curl "https://fucksornot.com/api/tags?page=1&limit=10" \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN"
```

Response:

```json theme={null}
{
  "tags": [
    {
      "id": "tag-uuid",
      "name": "gadget",
      "slug": "gadget",
      "upload_count": 150
    }
  ],
  "page": 1,
  "limit": 10
}
```

The `limit` defaults to **10** and can be set up to a maximum of **100**.

## Searching Tags

Find tags matching a query:

```bash theme={null}
curl "https://fucksornot.com/api/tags/search?q=tech&limit=10"
```

Response:

```json theme={null}
{
  "tags": [
    {
      "id": "tag-uuid",
      "name": "tech",
      "slug": "tech"
    },
    {
      "id": "tag-uuid-2",
      "name": "technology",
      "slug": "technology"
    }
  ]
}
```

For more advanced, meaning-based matching, FoN also offers `GET /api/tags/semantic-search`, an AI-powered semantic tag search.

## Filtering by Tags

Browse uploads matching one or more tag slugs using `GET /api/tags/browse`:

```bash theme={null}
curl "https://fucksornot.com/api/tags/browse?tags=gadget,tech" \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN"
```

Sort the results with the `sort` parameter (`name`, `date`, or `votes`; defaults to `date`):

```bash theme={null}
curl "https://fucksornot.com/api/tags/browse?tags=gadget,tech&sort=votes" \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN"
```

This endpoint also supports standard pagination via `page` and `limit`. There is no way to exclude tags — only matching by the provided `tags` is supported.

## Getting Upload Tags

Retrieve tags for a specific upload:

```bash theme={null}
curl https://fucksornot.com/api/uploads/UPLOAD_ID/tags
```

Response:

```json theme={null}
{
  "tags": [
    {
      "id": "tag-uuid",
      "name": "gadget",
      "slug": "gadget"
    }
  ]
}
```

## AI-Suggested Tags

FoN can suggest tags using AI, based on a description and/or an image. Send a JSON body with `description` and/or `imageUrl` (at least one is required):

```bash theme={null}
curl -X POST https://fucksornot.com/api/tags/suggest \
  -H "Cookie: auth-token=YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "A new gadget", "imageUrl": "https://example.com/image.jpg"}'
```

You can also send `multipart/form-data` with `description`, `image_url`, and/or `file` fields (e.g. to suggest tags directly from an uploaded image file).

Response:

```json theme={null}
{
  "suggestions": ["electronics", "gadget", "tech"],
  "fallback": false
}
```

`fallback` is `true` if the AI suggestion failed and a fallback heuristic was used instead. This endpoint is rate-limited, and may return a `503` error if tag generation fails entirely.

## Best Practices

<AccordionGroup>
  <Accordion title="Use descriptive tags">
    Choose tags that accurately describe the content for better discoverability.
  </Accordion>

  <Accordion title="Check existing tags">
    Search for existing tags before creating new ones to avoid duplicates.
  </Accordion>

  <Accordion title="Don't over-tag">
    Use 3-5 relevant tags rather than maxing out at 10 with irrelevant ones.
  </Accordion>
</AccordionGroup>