Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(docs): added api endpoint doc page (#390)

Corentin Thomasset42bc3c669840
diff --git a/.changeset/purple-carrots-tie.md b/.changeset/purple-carrots-tie.md
new file mode 100644
index 00000000..4252c9b8
--- /dev/null
+++ b/.changeset/purple-carrots-tie.md
@@ -0,0 +1,5 @@
+---
+"@papra/docs": patch
+---
+
+Added API endpoints documentation
diff --git a/apps/docs/src/assets/api-key-creation-1.png b/apps/docs/src/assets/api-key-creation-1.png
new file mode 100644
index 00000000..93d05e99
Binary files /dev/null and b/apps/docs/src/assets/api-key-creation-1.png differ
diff --git a/apps/docs/src/assets/api-key-creation-2.png b/apps/docs/src/assets/api-key-creation-2.png
new file mode 100644
index 00000000..254f3b42
Binary files /dev/null and b/apps/docs/src/assets/api-key-creation-2.png differ
diff --git a/apps/docs/src/config.data.ts b/apps/docs/src/config.data.ts
index 0d37d197..4745a33e 100644
--- a/apps/docs/src/config.data.ts
+++ b/apps/docs/src/config.data.ts
@@ -1,5 +1,7 @@
import type { ConfigDefinition, ConfigDefinitionElement } from 'figue';
import { isArray, isEmpty, isNil } from 'lodash-es';
+import { marked } from 'marked';
+
import { configDefinition } from '../../papra-server/src/modules/config/config';
function walk(configDefinition: ConfigDefinition, path: string[] = []): (ConfigDefinitionElement & { path: string[] })[] {
@@ -45,7 +47,7 @@ const rows = configDetails
});
const mdSections = rows.map(({ documentation, env, path, defaultValue }) => `
-### ${env}
+### ${env}
${documentation}
- Path: \`${path.join('.')}\`
@@ -85,4 +87,18 @@ const fullDotEnv = rows.map(({ env, defaultValue, documentation }) => {
].join('\n');
}).join('\n\n');
-export { fullDotEnv, mdSections };
+// Dirty hack to add the same anchors to the headings as the ones generated by Starlight
+const renderer = new marked.Renderer();
+renderer.heading = function ({ text, depth }) {
+ const slug = text.toLowerCase().replace(/\W+/g, '-');
+ return `
+<div class="sl-heading-wrapper level-h${depth}">
+<h${depth} id="${slug}">${text}</h${depth}>
+<a class="sl-anchor-link" href="#${slug}"><span aria-hidden="true" class="sl-anchor-icon"><svg width="16" height="16" viewBox="0 0 24 24"><path fill="currentcolor" d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 0 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 1 0-1.42-1.42Zm8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 0 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 1 0 1.42 1.42l3.88-3.89a4.49 4.49 0 0 0 0-6.33ZM8.83 15.17a1 1 0 0 0 1.1.22 1 1 0 0 0 .32-.22l4.92-4.92a1 1 0 0 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42Z"></path></svg></span><span class="sr-only">Section titled “Configuration files”</span></a>
+</div>
+`.trim().replace(/\n/g, '');
+};
+
+const sectionsHtml = marked.parse(mdSections, { renderer });
+
+export { fullDotEnv, mdSections, sectionsHtml };
diff --git a/apps/docs/src/content/docs/02-self-hosting/03-configuration.mdx b/apps/docs/src/content/docs/02-self-hosting/03-configuration.mdx
index fb30ddc4..1bb413b9 100644
--- a/apps/docs/src/content/docs/02-self-hosting/03-configuration.mdx
+++ b/apps/docs/src/content/docs/02-self-hosting/03-configuration.mdx
@@ -4,8 +4,7 @@ slug: self-hosting/configuration
description: Configure your self-hosted Papra instance.
---
-import { mdSections, fullDotEnv } from '../../../config.data.ts';
-import { marked } from 'marked';
+import { sectionsHtml, fullDotEnv } from '../../../config.data.ts';
import { Tabs, TabItem } from '@astrojs/starlight/components';
import { Aside } from '@astrojs/starlight/components';
import { Code } from '@astrojs/starlight/components';
@@ -84,5 +83,5 @@ Here is the full configuration file that you can use to configure Papra. The var
Here is the complete list of configuration variables that you can use to configure Papra. You can set these variables in the `.env` file or pass them as environment variables when running the Docker container.
-<Fragment set:html={marked.parse(mdSections)} />
+<Fragment set:html={sectionsHtml} />
diff --git a/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx b/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx
new file mode 100644
index 00000000..0161d96d
--- /dev/null
+++ b/apps/docs/src/content/docs/04-resources/03-api-endpoints.mdx
@@ -0,0 +1,210 @@
+---
+title: API Endpoints
+description: The list and details of all the API endpoints available in Papra.
+slug: resources/api-endpoints
+---
+
+## Authentication
+
+The public API uses a bearer token for authentication. You can get a token by logging to your Papra account and creating an API token.
+
+<details>
+
+<summary>How to create an API token</summary>
+
+![API Token](../../../assets/api-key-creation-1.png)
+![API Token](../../../assets/api-key-creation-2.png)
+
+</details>
+
+
+## Endpoints
+
+### Create a document
+
+**POST** `/api/organizations/:organizationId/documents`
+
+Create a new document in the organization.
+
+- Required API key permissions: `documents:create`
+- Body (form-data)
+ - `file`: The file to upload.
+ - `ocrLanguages`: (optional) The languages to use for OCR.
+- Response (JSON)
+ - `document`: The created document.
+
+### List documents
+
+**GET** `/api/organizations/:organizationId/documents`
+
+List all documents in the organization.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+ - `pageIndex`: (optional, default: 0) The page index to start from.
+ - `pageSize`: (optional, default: 100) The number of documents to return.
+ - `tags`: (optional) The tags IDs to filter by.
+- Response (JSON)
+ - `documents`: The list of documents.
+ - `documentsCount`: The total number of documents.
+
+### List deleted documents (trash)
+
+**GET** `/api/organizations/:organizationId/documents/deleted`
+
+List all deleted documents (in trash) in the organization.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+ - `pageIndex`: (optional, default: 0) The page index to start from.
+ - `pageSize`: (optional, default: 100) The number of documents to return.
+- Response (JSON)
+ - `documents`: The list of deleted documents.
+ - `documentsCount`: The total number of deleted documents.
+
+### Get a document
+
+**GET** `/api/organizations/:organizationId/documents/:documentId`
+
+Get a document by its ID.
+
+- Required API key permissions: `documents:read`
+- Response (JSON)
+ - `document`: The document.
+
+### Delete a document
+
+**DELETE** `/api/organizations/:organizationId/documents/:documentId`
+
+Delete a document by its ID.
+
+- Required API key permissions: `documents:delete`
+- Response: empty (204 status code)
+
+### Get a document file
+
+**GET** `/api/organizations/:organizationId/documents/:documentId/file`
+
+Get a document file content by its ID.
+
+- Required API key permissions: `documents:read`
+- Response: The document file stream.
+
+### Search documents
+
+**GET** `/api/organizations/:organizationId/documents/search`
+
+Search documents in the organization by name or content.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+ - `searchQuery`: The search query.
+ - `pageIndex`: (optional, default: 0) The page index to start from.
+ - `pageSize`: (optional, default: 100) The number of documents to return.
+- Response (JSON)
+ - `documents`: The list of documents.
+
+### Get organization documents statistics
+
+**GET** `/api/organizations/:organizationId/documents/statistics`
+
+Get the statistics (number of documents and total size) of the documents in the organization.
+
+- Required API key permissions: `documents:read`
+- Response (JSON)
+ - `organizationStats`: The organization documents statistics.
+ - `documentsCount`: The total number of documents.
+ - `documentsSize`: The total size of the documents.
+
+### Update a document
+
+**PATCH** `/api/organizations/:organizationId/documents/:documentId`
+
+Change the name or content (for search purposes) of a document.
+
+- Required API key permissions: `documents:update`
+- Body (form-data)
+ - `name`: (optional) The document name.
+ - `content`: (optional) The document content.
+- Response (JSON)
+ - `document`: The updated document.
+
+### Get document activity
+
+**GET** `/api/organizations/:organizationId/documents/:documentId/activity`
+
+Get the activity log of a document.
+
+- Required API key permissions: `documents:read`
+- Query parameters
+ - `pageIndex`: (optional, default: 0) The page index to start from.
+ - `pageSize`: (optional, default: 100) The number of documents to return.
+- Response (JSON)
+ - `activities`: The list of activities.
+
+### Create a tag
+
+**POST** `/api/organizations/:organizationId/tags`
+
+Create a new tag in the organization.
+
+- Required API key permissions: `tags:create`
+- Body (form-data)
+ - `name`: The tag name.
+ - `color`: The tag color in hex format (e.g. `#000000`).
+ - `description`: (optional) The tag description.
+- Response (JSON)
+ - `tag`: The created tag.
+
+### List tags
+
+**GET** `/api/organizations/:organizationId/tags`
+
+List all tags in the organization.
+
+- Required API key permissions: `tags:read`
+- Response (JSON)
+ - `tags`: The list of tags.
+
+### Update a tag
+
+**PUT** `/api/organizations/:organizationId/tags/:tagId`
+
+Change the name, color or description of a tag.
+
+- Required API key permissions: `tags:update`
+- Body
+ - `name`: (optional) The tag name.
+ - `color`: (optional) The tag color in hex format (e.g. `#000000`).
+ - `description`: (optional) The tag description.
+- Response (JSON)
+ - `tag`: The updated tag.
+
+### Delete a tag
+
+**DELETE** `/api/organizations/:organizationId/tags/:tagId`
+
+Delete a tag by its ID.
+
+- Required API key permissions: `tags:delete`
+- Response: empty (204 status code)
+
+### Add a tag to a document
+
+**POST** `/api/organizations/:organizationId/documents/:documentId/tags`
+
+Associate a tag to a document.
+
+- Required API key permissions: `tags:read` and `documents:update`
+- Body
+ - `tagId`: The tag ID.
+- Response: empty (204 status code)
+
+### Remove a tag from a document
+
+**DELETE** `/api/organizations/:organizationId/documents/:documentId/tags/:tagId`
+
+Remove a tag from a document.
+
+- Required API key permissions: `tags:read` and `documents:update`
+- Response: empty (204 status code)
diff --git a/apps/docs/src/content/navigation.ts b/apps/docs/src/content/navigation.ts
index eb5ca865..687e09fa 100644
--- a/apps/docs/src/content/navigation.ts
+++ b/apps/docs/src/content/navigation.ts
@@ -55,7 +55,10 @@ export const sidebar = [
target: '_blank',
},
},
-
+ {
+ label: 'API Endpoints',
+ slug: 'resources/api-endpoints',
+ },
],
},
] satisfies StarlightUserConfig['sidebar'];
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e3ede161..89622400 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,30 +4,6 @@ settings:
autoInstallPeers: true
excludeLinksFromLockfile: false
-catalogs:
- default:
- '@antfu/eslint-config':
- specifier: ^4.12.0
- version: 4.13.1
- '@types/node':
- specifier: ^22.15.21
- version: 22.15.21
- '@vitest/coverage-v8':
- specifier: ^3.0.2
- version: 3.1.3
- better-auth:
- specifier: ^1.2.8
- version: 1.2.8
- eslint:
- specifier: ^9.25.1
- version: 9.27.0
- typescript:
- specifier: ^5.6.2
- version: 5.8.3
- vitest:
- specifier: ^3.0.5
- version: 3.1.3
-
importers:
.:
@@ -77,7 +53,7 @@ importers:
devDependencies:
'@antfu/eslint-config':
specifier: ^3.13.0
'@iconify-json/tabler':
specifier: ^1.1.120
version: 1.2.18
@@ -8117,7 +8093,7 @@ snapshots:
'@jridgewell/gen-mapping': 0.3.8
'@jridgewell/trace-mapping': 0.3.25
dependencies:
'@antfu/install-pkg': 1.0.0
'@clack/prompts': 0.9.1
@@ -8126,7 +8102,7 @@ snapshots:
'@stylistic/eslint-plugin': 2.13.0([email protected]([email protected]))([email protected])
'@typescript-eslint/parser': 8.32.1([email protected]([email protected]))([email protected])
eslint: 9.27.0([email protected])
eslint-config-flat-gitignore: 1.0.0([email protected]([email protected]))
eslint-flat-config-utils: 1.1.0
@@ -11716,13 +11692,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/utils': 8.32.1([email protected]([email protected]))([email protected])
eslint: 9.27.0([email protected])
optionalDependencies:
typescript: 5.8.3
dependencies:
@@ -11759,6 +11735,15 @@ snapshots:
optionalDependencies:
vite: 5.4.19(@types/[email protected])
+ dependencies:
+ '@vitest/spy': 3.1.3
+ estree-walker: 3.0.3
+ magic-string: 0.30.17
+ optionalDependencies:
+ optional: true
+
'@vitest/[email protected]':
dependencies:
tinyrainbow: 2.0.0
@@ -16894,6 +16879,28 @@ snapshots:
- supports-color
- terser
+ dependencies:
+ cac: 6.7.14
+ debug: 4.4.1
+ es-module-lexer: 1.7.0
+ pathe: 2.0.3
+ transitivePeerDependencies:
+ - '@types/node'
+ - jiti
+ - less
+ - lightningcss
+ - sass
+ - sass-embedded
+ - stylus
+ - sugarss
+ - supports-color
+ - terser
+ - tsx
+ - yaml
+ optional: true
+
dependencies:
'@babel/core': 7.26.0
@@ -16971,6 +16978,48 @@ snapshots:
optionalDependencies:
+ dependencies:
+ '@vitest/expect': 3.1.3
+ '@vitest/pretty-format': 3.1.3
+ '@vitest/runner': 3.1.3
+ '@vitest/snapshot': 3.1.3
+ '@vitest/spy': 3.1.3
+ '@vitest/utils': 3.1.3
+ chai: 5.2.0
+ debug: 4.4.1
+ expect-type: 1.2.1
+ magic-string: 0.30.17
+ pathe: 2.0.3
+ std-env: 3.9.0
+ tinybench: 2.9.0
+ tinyexec: 0.3.2
+ tinyglobby: 0.2.14
+ tinypool: 1.0.2
+ tinyrainbow: 2.0.0
+ why-is-node-running: 2.3.0
+ optionalDependencies:
+ '@types/debug': 4.1.12
+ '@types/node': 22.15.21
+ jsdom: 26.0.0
+ transitivePeerDependencies:
+ - jiti
+ - less
+ - lightningcss
+ - msw
+ - sass
+ - sass-embedded
+ - stylus
+ - sugarss
+ - supports-color
+ - terser
+ - tsx
+ - yaml
+ optional: true
+
dependencies:
'@vitest/expect': 3.1.3