API docs by Redocly

DocPouch (1.20.3)

Download OpenAPI specification:

A light-weight, document-based database including user-management. DocPouch is meant for tests, development or internal applications, where security is not a major factor. The database is file and text based and therefore also not layed out for high performance. Instead the main focus of DocPouch is simplicity and a small footprint.

administration

User management endpoints

Authenticate a user

Request Body schema: application/json
required

User credentials for authentication

name
required
string

User name for authentication

password
required
string

Password is used as main authentication element

Responses

Request samples

Content type
application/json
{
  • "name": "Darth Vader",
  • "password": "darths-secret"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "isAdmin": true,
  • "userName": "string",
  • "_id": "string"
}

List user information

Get all user information as admin or your user information as user

Authorizations:
userAuthadminAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update user

Update any user (as admin) or your own user applying the provided attributes

Authorizations:
userAuthadminAuth
path Parameters
userID
required
string

Unique user ID

Request Body schema: application/json
required

Data object containing only the attributes to be updated

name
string

User names can be changed at any time and are not necessarily unique. Users are uniquely identified based on their id.

password
string

Password is used as main authentication element

email
string

User email address

isAdmin
boolean

Flag indicating if the user has administrator privileges

department
string

The department the user is part of

group
string

The group the user is part of

Responses

Request samples

Content type
application/json
{
  • "name": "Darth Vader",
  • "password": "darths-secret",
  • "email": "darth@gmail.com",
  • "isAdmin": false,
  • "department": "Administration",
  • "group": "The Magentas"
}

Create a new user

Authorizations:
adminAuth
Request Body schema: application/json
required

JSON body with all information to create a new user

name
required
string

User names can be changed at any time and are not necessarily unique. Users are uniquely identified based on their id.

password
required
string

Password is used as main authentication element

email
string

User email address

department
required
string

The department the user is part of

group
required
string

The group the user is part of

isAdmin
required
boolean

Flag indicating if the user has administrator privileges

Responses

Request samples

Content type
application/json
{
  • "name": "Darth Vader",
  • "password": "darths-secret",
  • "email": "darth@gmail.com",
  • "department": "Administration",
  • "group": "The Magentas",
  • "isAdmin": false
}

Response samples

Content type
application/json
{
  • "_id": "p3O5LB4T6C4PgkvW",
  • "name": "admin",
  • "email": "admin@example.com",
  • "department": "administration",
  • "group": "auto-created",
  • "isAdmin": true
}

Remove a user and all its documents

Authorizations:
adminAuth
path Parameters
userID
required
string

Unique user ID

Responses

Check for application updates

Check if a newer version of the application is available.

Responses

Response samples

Content type
application/json
{
  • "hasUpdate": true,
  • "currentVersion": "string",
  • "latestVersion": "string"
}

Export the database

Export full data as ZIP/JSON or export a single collection as JSON. Only available to administrators.

Authorizations:
adminAuth
query Parameters
scope
string
Default: "all"
Enum: "all" "users" "documents" "structures"

Which data scope to export

format
string
Default: "zip"
Enum: "zip" "json"

Export format. ZIP is only supported for scope=all.

Responses

Response samples

Content type
No sample

Import the database

Import data from JSON (full or scoped) or ZIP (full only). Only available to administrators.

Authorizations:
adminAuth
Request Body schema: multipart/form-data
required
file
string <binary>

JSON file (scoped or full) or ZIP file (full import)

scope
string
Default: "all"
Enum: "all" "users" "documents" "structures"

Import target scope. ZIP supports only scope=all.

mode
string
Default: "replace"
Enum: "replace" "add" "skip"

Import mode: replace (overwrite same _id), add (new _id for same _id), skip (ignore same _id)

Responses

Create a new API key

Creates a new long-lived API key for MCP clients and scripts. The full key is returned only once - copy it immediately. Maximum 10 keys per user.

Authorizations:
userAuth
Request Body schema: application/json
required

API key creation parameters

name
required
string

Descriptive name to identify the API key

expiresInDays
integer

Number of days until the key expires. Omit or set to undefined for no expiry.

Responses

Request samples

Content type
application/json
{
  • "name": "Home Assistant MCP",
  • "expiresInDays": 90
}

Response samples

Content type
application/json
{
  • "key": "docpouch_key_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  • "keyPrefix": "xxxxxxxx",
  • "name": "Home Assistant MCP",
  • "createdAt": 1750000000000,
  • "expiresAt": 1750860000000
}

List your API keys

Get all API keys belonging to the authenticated user. Does not return the full key, only metadata.

Authorizations:
userAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Delete an API key

Delete one of your own API keys

Authorizations:
userAuth
path Parameters
keyId
required
string

Unique API key ID

Responses

Admin - List all API keys

List all API keys across all users (admin only)

Authorizations:
adminAuth
query Parameters
userId
string

Filter by user ID (optional)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Admin - Revoke any API key

Revoke any user's API key (admin only)

Authorizations:
adminAuth
path Parameters
keyId
required
string

Unique API key ID

Responses

documents

Document management endpoints

Create a new document

Creates a new document. By default, the document is owned by the authenticated caller. If the anonymous property is set to true in the request body, the document is instead owned by the admin user and the creator's user ID is discarded. Anonymous creation requires the ANONYMOUS_DOCUMENTS_ENABLED environment variable to be set to true on the server; when the flag is off the request is rejected with HTTP 400 (error code ANONYMOUS_DOCUMENTS_DISABLED).

Authorizations:
userAuthadminAuth
Request Body schema: application/json
required

JSON body with all the information to create a new document

title
required
string

The title of the document

description
string

The description of the document

type
required
integer

Type of document - can be used by user for document organization

subType
required
integer

Sub-type of document - can be used by user for document organization

required
Array of objects

The content of the document as an array of field objects

shareWithGroup
required
boolean

If true, the document is shared with all users in the owner's group

shareWithDepartment
required
boolean

If true, the document is shared with all users in the owner's department

public
required
boolean

If true, the document can be read by everybody

anonymous
boolean
Default: false

If true, the document is owned by the admin user instead of the authenticated caller. The creator's user ID is discarded and cannot be recovered from the document. The flag is not stored on the document. Requires ANONYMOUS_DOCUMENTS_ENABLED=true on the server; otherwise the request is rejected with HTTP 400 (error code ANONYMOUS_DOCUMENTS_DISABLED).

Responses

Request samples

Content type
application/json
{
  • "title": "Mission Statement",
  • "description": "A brief description of the document",
  • "type": 17,
  • "subType": 11,
  • "content": [
    ],
  • "shareWithGroup": false,
  • "shareWithDepartment": false,
  • "public": false,
  • "anonymous": false
}

Response samples

Content type
application/json
{
  • "_id": "3ufDC0Rh5g7arSC9",
  • "owner": "p3O5LB4T6C4PgkvW",
  • "title": "Mission Statement",
  • "description": "A brief description of the document",
  • "type": 17,
  • "subType": 11,
  • "content": [
    ],
  • "shareWithGroup": false,
  • "shareWithDepartment": false,
  • "public": false
}

List documents

List all documents readable by the user. This includes documents owned by the user, shared with the user's group or department, or marked as public. For administrators, all documents are listed.

Authorizations:
userAuthadminAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a document based on a query object.

Fetch documents matching the query criteria that the user has access to. This includes own documents, documents shared with group/department, or public documents. Administrators can fetch any document.

Authorizations:
userAuthadminAuth
Request Body schema: application/json
required

An object describing the query to fetch the documents.

_id
string

Unique ID of document. Only used for queries and deletions

owner
string

The _id of the user who owns this document

type
integer

Type of document - can be used by user for document organization

subType
integer

Sub-type of document - can be used by user for document organization

title
string

The title of the document

description
string

The description of the document

shareWithGroup
boolean

If true, the document is shared with all users in the owner's group

shareWithDepartment
boolean

If true, the document is shared with all users in the owner's department

public
boolean

If true, the document can be read by everybody

Responses

Request samples

Content type
application/json
{
  • "_id": "3ufDC0Rh5g7arSC9",
  • "owner": "p3O5LB4T6C4PgkvW",
  • "type": 17,
  • "subType": 11,
  • "title": "Mission Statement",
  • "description": "A statement describing the corporate mission or how to achieve the corporate vision",
  • "shareWithGroup": false,
  • "shareWithDepartment": false,
  • "public": false
}

Response samples

Content type
application/json
[
  • {
    }
]

Update a document by applying the provided attributes

Users can update their own documents fully. Users with shared access (via group or department) can only update the content field. Only document owners can change sharing settings.

Authorizations:
userAuthadminAuth
path Parameters
documentID
required
string

Unique document ID

Request Body schema: application/json
required

Data object containing only the attributes to be updated

_id
required
string

Unique ID of document. Only used for queries and deletions

owner
required
string

The _id of the user who owns this document

title
required
string

The title of the document

description
string

The description of the document

type
required
integer

Type of document - can be used by user for document organization

subType
required
integer

Sub-type of document - can be used by user for document organization

required
Array of objects

The content of the document as an array of field objects

shareWithGroup
boolean

If true, the document is shared with all users in the owner's group

shareWithDepartment
boolean

If true, the document is shared with all users in the owner's department

public
required
boolean

If true, the document can be read by everybody

Responses

Request samples

Content type
application/json
{
  • "_id": "3ufDC0Rh5g7arSC9",
  • "owner": "p3O5LB4T6C4PgkvW",
  • "title": "Mission Statement",
  • "description": "A brief description of the document",
  • "type": 17,
  • "subType": 11,
  • "content": [
    ],
  • "shareWithGroup": false,
  • "shareWithDepartment": false,
  • "public": false
}

Remove a document

Authorizations:
userAuthadminAuth
path Parameters
documentID
required
string

Unique document ID

Responses

data structures

Data structure management endpoints

Create a new data structure

Authorizations:
adminAuth
Request Body schema: application/json
required

JSON body with all the information to create a new data structure

name
required
string

The name of the structure

description
string

The description of the structure

required
Array of objects (DataField)

Array of fields defining the structure

Responses

Request samples

Content type
application/json
{
  • "name": "City Info",
  • "description": "Data resulting from Vision-Mission-Value-Canvas",
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "tt5vo04DN3jm8Bqe",
  • "name": "City Info",
  • "description": "Data resulting from Vision-Mission-Value-Canvas",
  • "fields": [
    ]
}

Get all data structures

Fetch all data structures

Authorizations:
userAuthadminAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update the selected data structure applying the provided attributes

Authorizations:
adminAuth
path Parameters
structureID
required
string

Unique structure ID

Request Body schema: application/json
required

Data object containing only the attributes to be updated

_id
string

Unique ID of data structure, is used as type for documents

name
required
string

The name of the structure

description
string

The description of the structure

required
Array of objects (DataField)

Array of fields defining the structure

Responses

Request samples

Content type
application/json
{
  • "_id": "tt5vo04DN3jm8Bqe",
  • "name": "City Info",
  • "description": "Data resulting from Vision-Mission-Value-Canvas",
  • "fields": [
    ]
}

Remove a data structure

Authorizations:
adminAuth
path Parameters
structureID
required
string

Unique structure ID

Responses

openid connect

OpenID Connect (OIDC) provider endpoints

OpenID Connect discovery

Returns the OpenID Connect provider metadata. This is the standard OIDC discovery endpoint that all OIDC clients use to discover the provider's configuration.

Responses

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "authorization_endpoint": "http://example.com",
  • "token_endpoint": "http://example.com",
  • "userinfo_endpoint": "http://example.com",
  • "jwks_uri": "http://example.com",
  • "registration_endpoint": "http://example.com",
  • "scopes_supported": [
    ],
  • "response_types_supported": [
    ],
  • "grant_types_supported": [
    ],
  • "subject_types_supported": [
    ],
  • "id_token_signing_alg_values_supported": [
    ],
  • "token_endpoint_auth_methods_supported": [
    ]
}

OIDC Authorization endpoint

Standard OpenID Connect Authorization endpoint. Initiates the authentication request. Follows the OIDC Core specification.

query Parameters
client_id
required
string

Client identifier

response_type
required
string
Enum: "code" "id_token" "code id_token"

OAuth response type

scope
required
string

Space-separated list of scopes (e.g. openid profile)

redirect_uri
required
string <uri>

Client redirect URI

state
string

Opaque value used to maintain state

nonce
string

String value used to associate a client session with an ID token

Responses

OIDC Token endpoint

Standard OpenID Connect Token endpoint. Exchanges authorization codes for tokens and refreshes tokens.

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "authorization_code" "refresh_token" "client_credentials"

OAuth grant type

code
string

Authorization code (required for authorization_code grant)

refresh_token
string

Refresh token (required for refresh_token grant)

redirect_uri
string <uri>

Redirect URI (required for authorization_code grant)

client_id
string

Client identifier

client_secret
string

Client secret (required for confidential clients)

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "string",
  • "expires_in": 0,
  • "id_token": "string",
  • "refresh_token": "string",
  • "scope": "string"
}

OIDC UserInfo endpoint

Standard OpenID Connect UserInfo endpoint. Returns claims about the authenticated user.

Authorizations:
userAuth

Responses

Response samples

Content type
application/json
{
  • "sub": "string",
  • "name": "string",
  • "email": "string",
  • "department": "string",
  • "group": "string"
}

OIDC JWKS endpoint

Returns the JSON Web Key Set used by the OIDC provider for token signing. Used by clients to verify ID token signatures.

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

OIDC End Session endpoint

Destroys the user's OIDC session and redirects to the post-logout redirect URI. This is the standard OIDC logout endpoint.

query Parameters
post_logout_redirect_uri
required
string <uri>

URI to redirect the user after logout. Must be registered in the client's post_logout_redirect_uris.

id_token_hint
string

ID token previously issued to the client. Used to verify the user's identity.

Responses

OIDC Token Revocation endpoint

Revokes an access or refresh token, rendering it unusable. Clients can call this to explicitly invalidate tokens.

Request Body schema: application/x-www-form-urlencoded
required
token
required
string

The token to be revoked

token_type_hint
string
Enum: "access_token" "refresh_token"

Type of token to be revoked (optional but recommended)

Responses

OIDC Pushed Authentication Request (PAR) endpoint

Pushes an authorization request to the server and receives a unique request URI. Used for improved security and pre-authorization.

Request Body schema: application/x-www-form-urlencoded
required
response_type
required
string
Value: "code"

OAuth response type

client_id
required
string

Client identifier

redirect_uri
required
string <uri>

Redirect URI

scope
required
string

OAuth scope

state
required
string

Opaque value for CSRF protection

code_challenge
required
string

PKCE code challenge

code_challenge_method
required
string
Enum: "S256" "plain"

PKCE code challenge method

Responses

Response samples

Content type
application/json
{
  • "request_uri": "string",
  • "expires_in": 0
}

Register a new OIDC client (dynamic registration)

Register a new OIDC client application dynamically. Requires an initial access token provided in the Authorization header.

Authorizations:
oidcRegistrationToken
Request Body schema: application/json
required

Client metadata for registration

client_name
required
string

Human-readable client name

redirect_uris
required
Array of strings <uri> [ items <uri > ]

List of allowed redirect URIs

grant_types
Array of strings

List of OAuth grant types

response_types
Array of strings

List of OAuth response types

scope
string

Space-separated list of default scopes

token_endpoint_auth_method
string
Enum: "client_secret_basic" "client_secret_post" "none"

Token endpoint authentication method

application_type
string
Enum: "web" "native"

Application type

logo_uri
string <uri>

URL for the client logo

client_uri
string <uri>

URL of the client application

policy_uri
string <uri>

URL of the client's privacy policy

tos_uri
string <uri>

URL of the client's terms of service

post_logout_redirect_uris
Array of strings <uri> [ items <uri > ]

List of allowed post-logout redirect URIs

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "client_secret_expires_at": 0,
  • "client_id_issued_at": 0,
  • "registration_access_token": "string",
  • "registration_client_uri": "http://example.com",
  • "client_name": "string",
  • "redirect_uris": [],
  • "grant_types": [
    ],
  • "response_types": [
    ],
  • "scope": "string",
  • "token_endpoint_auth_method": "string"
}

Read OIDC client details

Retrieve the registration state of an existing OIDC client. Requires the registration access token issued during client registration.

Authorizations:
oidcRegistrationToken
path Parameters
clientId
required
string

The client identifier

Responses

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "client_secret_expires_at": 0,
  • "client_id_issued_at": 0,
  • "registration_access_token": "string",
  • "registration_client_uri": "http://example.com",
  • "client_name": "string",
  • "redirect_uris": [],
  • "grant_types": [
    ],
  • "response_types": [
    ],
  • "scope": "string",
  • "token_endpoint_auth_method": "string"
}

Update OIDC client registration

Update the registration of an existing OIDC client. Requires the registration access token issued during client registration.

Authorizations:
oidcRegistrationToken
path Parameters
clientId
required
string

The client identifier

Request Body schema: application/json
required

Updated client metadata

client_name
required
string

Human-readable client name

redirect_uris
required
Array of strings <uri> [ items <uri > ]

List of allowed redirect URIs

grant_types
Array of strings

List of OAuth grant types

response_types
Array of strings

List of OAuth response types

scope
string

Space-separated list of default scopes

token_endpoint_auth_method
string
Enum: "client_secret_basic" "client_secret_post" "none"

Token endpoint authentication method

application_type
string
Enum: "web" "native"

Application type

logo_uri
string <uri>

URL for the client logo

client_uri
string <uri>

URL of the client application

policy_uri
string <uri>

URL of the client's privacy policy

tos_uri
string <uri>

URL of the client's terms of service

post_logout_redirect_uris
Array of strings <uri> [ items <uri > ]

List of allowed post-logout redirect URIs

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "client_secret": "string",
  • "client_secret_expires_at": 0,
  • "client_id_issued_at": 0,
  • "registration_access_token": "string",
  • "registration_client_uri": "http://example.com",
  • "client_name": "string",
  • "redirect_uris": [],
  • "grant_types": [
    ],
  • "response_types": [
    ],
  • "scope": "string",
  • "token_endpoint_auth_method": "string"
}

Delete OIDC client registration

Delete an existing OIDC client. Requires the registration access token issued during client registration.

Authorizations:
oidcRegistrationToken
path Parameters
clientId
required
string

The client identifier

Responses

OIDC login page

Serves the OIDC login page for user authentication during the authorization flow.

path Parameters
uid
required
string

Interaction UID

Responses

OIDC interaction details

Returns details about an ongoing OIDC interaction, such as the client name and prompt type.

path Parameters
uid
required
string

Interaction UID

Responses

Response samples

Content type
application/json
{
  • "clientName": "string",
  • "prompt": "string"
}