API 2.0

UserManual API Reference

UserManual is a SaaS platform designed to help product companies improve their customer support. Our tool offers a range of features, including the management of product manuals, provision of product downloads and firmware upgrades, hosting of frequently asked questions, and creation of a community for your customers.

In this API reference we will explain how to interact with our Server API. You will need this API if you want to upload or change, for example, documents or products on UserManual through your application.

Don't hesitate to contact us through the chat in the right bottom corner if you have questions.

Client Libraries
Node
$ npm install usermanual-api
NODE

Base URL

All API requests should be done to our base URL

Base URL
https://api-prod.usermanual.com

Authentication

UserManual uses API keys to allow access to the API. You can find the API key in your Dashboard → Settings → API Keys.

UserManual expects the API key to be included in all API requests to the server in a header that looks like the following:

api-key: API_KEY

To verify if your authentication and request is valid you can use this endpoint. If the authorization is successful it will respond with the message "Authorized"

Endpoint
GET
/v2/auth
Sample Response
{
    "message": "Authorized",
    "displayName": "ACME Company LTD",
    "slug": "acme",
    "id": 1
}

Products

Add and edit products

Endpoints
POST/v2/products
GET/v2/products/:id

The product object

This is the main object of UserManual and this describes the product

idstring

The identifier of the product

namestring

The name of the product

statusstring

The status of the product this can be "Active" or "Draft"

barcodesarray

The barcodes of the product. This is an array for EAN numbers

modelNumberstring

The model number is the identifier of the product mostly used inside the product organization

translationsarray

Product translations

Product Translations
idstring

The identifier of the product translation

namestring

The name of the product translation

shortDescriptionstring

The short description of the product translation

slugstring

The slug of the product translation

localeIdstring

The locale of the product translation

assetsarray

The assets of the product

Assets
idstring

The identifier of the asset

typestring

The type of asset. Can have the following values: "MediaLibrary", "OrganizationAvatar", "UserAvatar"

contentTypestring

The content type of the asset. Can have the following values: "image/png" or "image/jpeg"

fileNamestring

The name of the asset

orderinteger

The order that the asset will be presented on the frontend

documentsarray
Product Documents
idstring

The identifier of the document

variantstring

The variant of the document. Can have the following values: "PDF" or "Doc"

statusstring

The status of the document. Can have the following values: "Active" or "Draft"

orderinteger

The order of the product document

Example Object
{
    "id": "fa6ca91e-a00a-4727-b643-1d9f7bc4b489",
    "name": "ZV-1",
    "status": "Active",
    "barcodes": [],
    "modelNumber": "ZV-1",
    "translations": [
        {
            "id": "27d07e9f-686a-4d83-a4e8-4a8f54bf11ee",
            "name": "ZV-1",
            "shortDescription": null,
            "slug": "zv-1",
            "localeId": "en-US"
        }
    ],
    "assets": [
        {
            "id": "d021314c-5c07-49cd-bb19-bd194bf90bf1",
            "type": "MediaLibrary",
            "contentType": "image/jpeg",
            "fileName": "xm4060gtx.jpeg",
            "order": 3
        },
        {
            "id": "8e6f4a59-6548-4f43-8f16-6a7cd400f441",
            "type": "MediaLibrary",
            "contentType": "image/jpeg",
            "fileName": "543cfbee16436d6abe99f01717946365.jpeg",
            "order": 0
        },
        {
            "id": "a22c3573-a96d-4db9-945a-d6b5faddd479",
            "type": "MediaLibrary",
            "contentType": "image/jpeg",
            "fileName": "3a882b48f293cc77c6a232424cf0615c.jpeg",
            "order": 1
        },
        {
            "id": "d4dd469d-a6ff-405a-b61c-7e0685df227f",
            "type": "MediaLibrary",
            "contentType": "image/jpeg",
            "fileName": "d3d0584aafa823b54acab4653c3ddeea.jpeg",
            "order": 2
        }
    ],
    "documents": [
        {
            "id": "5e859b35-2220-43ed-9545-e6582cbf06fd",
            "variant": "Doc",
            "slug": "sony-test-manual",
            "status": "Active",
            "order": 0
        },
        {
            "id": "2fff82e9-e02c-4399-9588-4deae4b1a195",
            "variant": "PDF",
            "status": "Active",
            "type": "Manual",
            "order": 1
        },
        {
            "id": "8327872f-da2c-4e1f-abfc-d7ac97c4e746",
            "variant": "PDF",
            "status": "Active",
            "type": "Manual",
            "order": 2
        },
        {
            "id": "31880677-6f36-4214-b686-397475c08910",
            "variant": "PDF",
            "status": "Active",
            "type": "Manual",
            "order": 3
        }
    ]
}

Create a product

Parameters

namestringRequired

The name of the product you want to create.

statusstringRequired

The status of the product this can be "Active" or "Draft"

translationsarray
Product Translations
namestringRequired

The name of the product translation

slugstringRequired

The slug of the product translation

shortDescriptionstring

The short description of the product translation

localeIdstringRequired

The locale of the product translation

assetsarray
Product Assets
assetIdstringRequired

The identifier of the asset

orderintegerRequired

The order of the asset

documentsarray
Product Documents
idstringRequired

The identifier of the document you want to add to the product

typestringRequired

The type of the product this can be "PDF" or "Doc"

Endpoint
POST
/v2/products
Sample request
var data = {
    "translations": [{
        "name": "a6400",
        "slug": "a6400",
        "shortDescription": "Camera",
        "localeId": "en-US"
    }],
    "assets": [{
        "assetId": "a22c3573-a96d-4db9-945a-d6b5faddd479",
        "order": 0
    }],
    "documents": [{
        "id": "8327872f-da2c-4e1f-abfc-d7ac97c4e746",
        "type": "PDF"
    }],
    "status": "Draft",
    "name": "A6400"
}


fetch('https://api-prod.usermanual.com/v2/products', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'api-key' : API_KEY
  }
})

Retrieve a product

Parameters

idstringRequired

The identifier of the product

Endpoint
GET
/v2/products/:id
Sample request
fetch(`https://api-prod.usermanual.com/v2/products/${ID}`, {
  method: 'GET',
  headers: {
    'api-key' : API_KEY
  }
})

Assets

Upload assets that you can use in your products

Endpoints
POST/v2/assets
GET/v2/assets/:id
PATCH/v2/assets/:id

The asset object

These are the attributes of the asset object

idstring

The identifier of the asset

fileName

The fileName of the asset

contentTypestring

The content type of the asset. Can have the following values: "image/png" or "image/jpeg"

typestring

The asset type. Can have the following values: "MediaLibrary", "OrganizationAvatar", "UserAvatar"

Example Object
{
    "id": "aae369ae-c389-4574-bbde-cfde8abd9729",
    "contentType": "image/png",
    "type": "MediaLibrary",
    "fileName": "test.png",
    "createdAt": "2023-02-08T18:23:06.516Z",
    "completedAt": null
}

Create an asset

Before you can upload an asset to UserManual.com you must create a new asset.

The server will return a pre-signed upload URL where you can upload your asset.

After uploading the file you must notify our server that the upload is finished.

Parameters

namestringRequired

The name of the asset you want to upload.

typestringRequired

The asset type. Can have the following values: "MediaLibrary", "OrganizationAvatar", "UserAvatar"

contentTypestringRequired

The content type of the asset. Can have the following values: "image/png" or "image/jpeg"

Endpoint
POST
/v2/assets
Sample Request
var data = {
    "name": "test.png",
    "type": "MediaLibrary",
    "contentType": "image/png"
}


fetch('https://api-prod.usermanual.com/v2/assets', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'api-key' : API_KEY
  }
})

Retrieve an asset

Parameters

idstringRequired

The identifier of the asset

Endpoint
GET
/v2/assets/:id
Sample request
fetch(`https://api-prod.usermanual.com/v2/assets/${ID}`, {
  method: 'GET',
  headers: {
    'api-key' : API_KEY
  }
})

Upload an asset

After you create an asset you will receive an Amazon signed URL where you can upload your image file. We suggest to upload the file directly from the clients browser to spare your server load. You can look at the example using Axios in TypeScript.

When the file upload is finished you must notify our server.

Sample request
import axios from 'axios';


axios.put(signedUploadURL, file, {
  headers: {
    "Content-Type": "image/png"
  },
  onUploadProgress: (e) => {
    //  Show progress
    const percentComplete = Math.round((e.loaded * 100) / e.total);
    console.log(percentComplete);
  },
});

Upload asset finished

After uploading your file to Amazon S3 you must notify our server on this endpoint that the upload is complete.

Parameters

idstringRequired

The identifier of the asset

uploadCompletedboolean

Notify the server that you uploaded the asset to the Amazon S3 bucket

Endpoint
PATCH
/v2/assets/:id
Sample request
var data = {
  "uploadCompleted" : true
}


fetch(`https://api-prod.usermanual.com/v2/assets/${ID}`, {
  method: 'PATCH',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'api-key' : API_KEY
  }
})

PDF documents

PDF Documents

Endpoint
POST/v2/pdf-documents
GET/v2/pdf-documents/:id
PATCH/v2/pdf-documents/:id/files/:fileId

The PDF document object

These are the attributes of the PDF document object

idstring

The identifier of the PDF document

namestring

The name of the PDF document

statusstring

The status of the product this can be "Active" or "Draft"

typestring

The type of the product this can be "Manual", "Specification", "Wiring" or "Other"

activeFileobject

The version of the file that is currently active

Active File
idstring

The file identifier

createdAtstring

The file creation date

processedAtstring

The date when the file has been completed by our worker

translationsarray

The PDF document translations

PDF Document Translations
idstring

The identifier of the PDF document translation

namestring

The name of the PDF document translation

slugstring

The slug of the PDF document translation

localeIdstring

The locale of the PDF document translation

typeOtherstring

The translation of the type. If you have selected "other" on the PDF document type.

Example Object
{
    "id": "b8f9130a-a3a3-45f6-8294-eed465cd5334",
    "translations": [
        {
            "id": "dec09df3-9c17-4a89-b1a5-9eb98e0ecb37",
            "name": "A6400 User Manual",
            "slug": "a6400-user-manual",
            "typeOther": null,
            "localeId": "en-US"
        }
    ],
    "activeFile": {
        "id": "a0e0ff79-2c96-4295-974a-143e416d6e5d",
        "createdAt": "2023-02-11T21:12:40.576Z",
        "processedAt": null
    },
    "type": "Manual",
    "status": "Draft",
    "name": "A6400 User Manual",
    "activeLocales": [
        "en-US"
    ]
}

Create a PDF document

Before you can upload your PDF file to UserManual.com you must create a new PDF document.

The server will return a pre-signed upload URL where you can upload your PDF file.

After uploading the file you must notify our server that the upload is finished.

Parameters

namestringRequired

The name of the PDF document

fileNamestringRequired

The name of the PDF file you want to upload

typestringRequired

The PDF document type. Can have the following values: "Manual", "Specifications", "Wiring" or "Other"

translationsarray

The PDF document translations

PDF Document Translations
idstring

The identifier of the PDF document translation

namestring

The name of the PDF document translation

slugstring

The slug of the PDF document translation

localeIdstring

The locale of the PDF document translation

typeOtherstring

The translation of the type. If you have selected "other" on the PDF document type.

metadataobject

Add extra metadata custom fields

PDF Document Metadata
customFieldstring

The first custom field

customField2string

The second custom field

customField3string

The third custom field

Endpoint
POST
/v2/pdf-documents
Sample request
var data = {
    "translations": [{
        "name": "A6400 User Manual",
        "slug": "a6400-user-manual",
        "localeId": "en-US"
    },{
        "name": "A6400 bedienungsanleitung",
        "slug": "a6400-bedienungsanleitung",
        "localeId": "de-DE"
    }],
    "type": "Manual",
    "fileName": "sony-a6400-manual.pdf",
    "name": "A6400 User Manual"
}


fetch('https://api-prod.usermanual.com/v2/pdf-documents', {
  method: 'POST',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'api-key' : API_KEY
  }
})

Retrieve a PDF document

Parameters

idstringRequiredURL Parameter

The identifier of the PDF document

Endpoints
GET
/v2/pdf-documents/:id
Sample request
fetch(`https://api-prod.usermanual.com/v2/pdf-documents/${ID}`, {
  method: 'GET',
  headers: {
    'api-key' : API_KEY
  }
})

Upload PDF file

After you create a PDF document you will receive an Amazon signed URL where you can upload your pdf file. We suggest to upload the file directly from the clients browser to spare your server load. You can look at the example using Axios in TypeScript.

When the file upload is finished you must notify our server.

Sample request
import axios from 'axios';


axios.put(signedUploadURL, file, {
  headers: {
    "Content-Type": "application/pdf"
  },
  onUploadProgress: (e) => {
    //  Show progress
    const percentComplete = Math.round((e.loaded * 100) / e.total);
    console.log(percentComplete);
  },
});

Upload PDF file finished

After uploading your PDF file to Amazon S3 you must notify our server on this endpoint that the upload is completed. After this the PDF will be processed by our worker

idstringRequiredURL Parameter

The identifier of the PDF document

fileIdstringRequiredURL Parameter

The identifier of the PDF file

uploadCompletedboolean

Notify the server that you uploaded the PDF flie to the Amazon S3 bucket

Endpoint
PATCH
/v2/pdf-documents/:id/files/:fileId
Sample request
var data = {
  "uploadCompleted" : true
}


fetch(`https://api-prod.usermanual.com/v2/pdf-documents/${ID}/files/${FILE_ID}`, {
  method: 'PATCH',
  body: JSON.stringify(data),
  headers: {
    'Content-Type' : 'application/json',
    'api-key' : API_KEY
  }
})