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.mdnew file mode 100644index 00000000..4252c9b8--- /dev/null+++ b/.changeset/purple-carrots-tie.md@@ -0,0 +1,5 @@+---+"@papra/docs": patch+---++Added API endpoints documentationdiff --git a/apps/docs/src/assets/api-key-creation-1.png b/apps/docs/src/assets/api-key-creation-1.pngnew file mode 100644index 00000000..93d05e99Binary files /dev/null and b/apps/docs/src/assets/api-key-creation-1.png differdiff --git a/apps/docs/src/assets/api-key-creation-2.png b/apps/docs/src/assets/api-key-creation-2.pngnew file mode 100644index 00000000..254f3b42Binary files /dev/null and b/apps/docs/src/assets/api-key-creation-2.png differdiff --git a/apps/docs/src/config.data.ts b/apps/docs/src/config.data.tsindex 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.mdxindex 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/configurationdescription: 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 varHere 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.mdxnew file mode 100644index 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>+++++</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.tsindex 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.yamlindex e3ede161..89622400 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -4,30 +4,6 @@ settings:autoInstallPeers: trueexcludeLinksFromLockfile: 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- version: 3.16.0(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))(@vue/[email protected])([email protected]([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected]))+ version: 3.16.0(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))(@vue/[email protected])([email protected]([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])([email protected]))'@iconify-json/tabler':specifier: ^1.1.120version: 1.2.18@@ -8117,7 +8093,7 @@ snapshots:'@jridgewell/gen-mapping': 0.3.8'@jridgewell/trace-mapping': 0.3.25- '@antfu/[email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))(@vue/[email protected])([email protected]([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected]))':+ '@antfu/[email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))(@vue/[email protected])([email protected]([email protected]))([email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])([email protected]))':dependencies:'@antfu/install-pkg': 1.0.0'@clack/prompts': 0.9.1@@ -8126,7 +8102,7 @@ snapshots:'@typescript-eslint/eslint-plugin': 8.32.1(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])- '@vitest/eslint-plugin': 1.1.25(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected]))+ '@vitest/eslint-plugin': 1.1.25(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected])([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- '@vitest/[email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected]))':+ '@vitest/[email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])([email protected]))':dependencies:eslint: 9.27.0([email protected])optionalDependencies:typescript: 5.8.3+ vitest: 3.1.3(@types/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])([email protected])'@vitest/[email protected]([email protected]([email protected]))([email protected])([email protected](@types/[email protected])(@types/[email protected])([email protected]([email protected])))':dependencies:@@ -11759,6 +11735,15 @@ snapshots:optionalDependencies:vite: 5.4.19(@types/[email protected])+ '@vitest/[email protected]([email protected](@types/[email protected])([email protected])([email protected])([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+ [email protected](@types/[email protected])([email protected])([email protected])([email protected]):+ 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+[email protected]([email protected])([email protected](@types/[email protected])([email protected])([email protected])([email protected])):dependencies:'@babel/core': 7.26.0@@ -16971,6 +16978,48 @@ snapshots:optionalDependencies:+ [email protected](@types/[email protected])(@types/[email protected])([email protected])([email protected])([email protected])([email protected]):+ dependencies:+ '@vitest/expect': 3.1.3+ '@vitest/mocker': 3.1.3([email protected](@types/[email protected])([email protected])([email protected])([email protected]))+ '@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+ vite-node: 3.1.3(@types/[email protected])([email protected])([email protected])([email protected])+ 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+[email protected](@types/[email protected])(@types/[email protected])([email protected]([email protected])):dependencies:'@vitest/expect': 3.1.3