Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we
store it to create your key and to recognise you if you sign in with another
provider. See our Privacy Policy and
Terms.
openapi: 3.2.0
info:
description: Linkwarden OpenAPI Documentation.
version: 1.0.0
title: Introduction Preserved API
license:
name: GNU Affero General Public License v3.0
url: https://www.gnu.org/licenses/agpl-3.0.html
tags:
- name: Preserved
paths:
/api/v1/preserved/token:
get:
tags:
- Preserved
summary: Creates a short-lived preserved format URL
parameters:
- name: linkId
in: query
required: true
description: The ID of the link whose archived format should be accessed.
schema:
type: integer
- name: format
in: query
required: false
description: 'The numeric value corresponding to the preserved format:
- `0`: PNG
- `1`: JPEG
- `2`: PDF
- `3`: Readability JSON
- `4`: Monolith HTML
'
schema:
type: integer
enum:
- 0
- 1
- 2
- 3
- 4
responses:
'200':
description: Signed preserved format URL created successfully.
content:
application/json:
schema:
type: object
properties:
response:
$ref: '#/components/schemas/PreservedFormatUrl'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
description: 'Returns a short-lived signed URL for loading an archived format from the configured user content domain.
This route supports authenticated requests and can also work for public links if the archived item belongs to a public collection.'
operationId: getApiV1PreservedToken
x-operation-id-source: derived
/api/v1/preserved/view:
get:
tags:
- Preserved
summary: Streams an archived format from the user content domain
parameters:
- name: token
in: query
required: true
description: The short-lived signed token returned by `/api/v1/preserved/token`.
schema:
type: string
- name: download
in: query
required: false
description: If set to `1`, the response is served as a file download.
schema:
type: string
enum:
- '1'
responses:
'200':
description: Archived format streamed successfully.
content:
text/html:
schema:
type: string
application/pdf:
schema:
type: string
format: binary
image/png:
schema:
type: string
format: binary
image/jpeg:
schema:
type: string
format: binary
application/json:
schema:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
description: 'Streams an archived format by validating a short-lived signed token.
This route is intended to be served only on the hostname configured in `NEXT_PUBLIC_USER_CONTENT_DOMAIN`.'
operationId: getApiV1PreservedView
x-operation-id-source: derived
components:
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Forbidden:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
BadRequest:
description: Bad request error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
schemas:
ErrorResponse:
type: object
properties:
response:
type: string
PreservedFormatUrl:
type: object
properties:
url:
type: string
format: uri
example: https://usercontent.example.com/api/v1/preserved/view?token=eyJ...
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT