mirror of
https://github.com/wahyd4/links.git
synced 2026-08-09 05:06:16 +10:00
70 lines
3.7 KiB
Plaintext
70 lines
3.7 KiB
Plaintext
# 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
|
||
|
||
|
||
```
|
||
|
||
### 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 |
|