# GoLinks API

> GoLinks is a self-hosted link and content management system. It lets you create short links, bookmark pages with auto-extracted metadata, manage image collections, upload files, write Markdown blog posts, and serve random images from a personal library.

## What you can do with this API

- **List short links** (`/api/links`) — GET a paginated list of all short links with their aliases, target URLs, tags, and click counts
- **Most visited links** (`/api/links/most-visited`) — GET links sorted by visit count descending (only links with at least one click)
- **Bookmark pages** (`/api/pages`) — POST a URL and the server auto-fetches the title, description and screenshot in the background
- **Write blog posts** (`/api/posts`) — Create Markdown posts with tag categorisation
- **Manage image collections** (`/api/collections`) — Group images into named albums; upload multiple images at once
- **Upload & share files** (`/api/files`) — Upload any file, make it public with a shareable token URL, set expiry dates
- **Random image endpoint** (`/api/images/random/{width}/{height}/`) — Returns a random image from the server's library at any size; add `?fit=crop` to crop to exact dimensions
- **Import external images** (`/import/images/{url-without-scheme}`) — Reference an external image URL; the server downloads and self-hosts it in the background

## API reference

- Full OpenAPI 3.0.3 spec: /static/openapi.yaml
- Interactive docs: /ui/api-docs/

## Key patterns

### Embedding images in Markdown
```markdown
![placeholder](https://your-domain/api/images/random/400/300/?fit=crop&v=1234567890)
![photo](https://your-domain/import/images/example.com/path/to/photo.jpg)
```

### File sharing workflow
1. Upload a file: `POST /api/files` (multipart/form-data, field: `files`)
2. Make it public: `POST /api/files/{id}/toggle-public`  → get `public_url`
3. Share the URL: `/public/files/{token}/` — no authentication required

### Pagination
All list endpoints accept `?page=` (1-based) and `?page_size=`. Responses are enveloped:
```json
{ "count": 42, "next": "...", "previous": null, "results": [...] }
```

## Authentication

No authentication is currently required.

## Operations quick reference

| operationId | Method | Path | Description |
|---|---|---|---|
| listLinks | GET | /api/links | List all short links |
| listMostVisitedLinks | GET | /api/links/most-visited | Links sorted by visit count |
| listPages | GET | /api/pages | List bookmarked pages |
| createPage | POST | /api/pages | Bookmark a new URL |
| listPosts | GET | /api/posts | List blog posts |
| createPost | POST | /api/posts | Create a blog post |
| listCollections | GET | /api/collections | List image collections |
| createCollection | POST | /api/collections | Create a collection |
| deleteCollection | DELETE | /api/collections/{id} | Delete a collection |
| uploadImagesToCollection | POST | /api/collections/{id}/upload_images | Upload images |
| deleteImage | DELETE | /api/images/{id} | Delete an image |
| listFiles | GET | /api/files | List uploaded files |
| uploadFiles | POST | /api/files | Upload files |
| getFile | GET | /api/files/{id} | Get file metadata |
| deleteFile | DELETE | /api/files/{id} | Delete a file |
| downloadFile | GET | /api/files/{id}/download | Download/view file |
| toggleFilePublic | POST | /api/files/{id}/toggle-public | Toggle public sharing |
| setFileExpiry | POST | /api/files/{id}/set-expiry | Set expiry date |
| getPublicFile | GET | /public/files/{token}/ | Access public file |
| getRandomImage | GET | /api/images/random/ | Random image (default size) |
| getRandomImageSized | GET | /api/images/random/{w}/{h}/ | Random image at W×H |
| importExternalImage | GET | /import/images/{url} | Import & cache external image |
