Knowledge Base API Basics

You can Create Knowledge Base Articles and Manage the Knowledge Base with Liferay’s Knowledge Base app, but you can also use Liferay’s REST APIs. Call these services to create and manage content for your Knowledge Base.

Adding a Knowledge Base Article

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2026.q1.9-lts

Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.

Then follow these steps:

Download and unzip Knowledge Base API Basics.

curl https://resources.learn.liferay.com/examples/liferay-t3x7.zip -O

unzip liferay-t3x7.zip

When signed in, retrieve the site’s ID. You’ll use this ID in several service calls.

Use the cURL script to add a new Knowledge Base article to your site. On the command line, navigate to the curl folder. Execute the KnowledgeBaseArticles_POST_ToSite.sh script with your site ID as a parameter. For example,

./KnowledgeBaseArticles_POST_ToSite.sh 1234

The JSON response shows a new Knowledge Base article has been added:

{
  "articleBody" : "Foo",
  "creator" : {
    "additionalName" : "",
    "contentType" : "UserAccount",
    "familyName" : "Test",
    "givenName" : "Test",
    "id" : 20125,
    "name" : "Test Test"
  },
  "customFields" : [ ],
  "dateCreated" : "2022-07-28T21:25:57Z",
  "dateModified" : "2022-07-28T21:25:57Z",
  "description" : "",
  "encodingFormat" : "text/html",
  "externalReferenceCode" : "0bace9ad-39ea-79b5-902e-c873806b8bd7",
  "friendlyUrlPath" : "able",
  "id" : 42447,
  "keywords" : [ ],
  "numberOfAttachments" : 0,
  "numberOfKnowledgeBaseArticles" : 0,
  "parentKnowledgeBaseArticleId" : 0,
  "relatedContents" : [ ],
  "siteId" : 20121,
  "subscribed" : false,
  "taxonomyCategoryBriefs" : [ ],
  "title" : "Able"
}

Click the Menu icon () and navigate to Content & Data → Knowledge Base. See that a new Knowledge Base article has been added.
The REST service can also be called using the Java client. Navigate out of the curl folder and into the java folder. Compile the source files:
```
javac -classpath .:* *.java
```
Run the KnowledgeBaseArticles_POST_ToSite.java class. Replace the siteId system property value with your site’s ID.
```
java -classpath .:* -DsiteId=1234 KnowledgeBaseArticles_POST_ToSite
```
The Java class created a new Knowledge Base article.

Examine the cURL Command

The KnowledgeBaseArticles_POST_ToSite.sh script calls the REST service with a cURL command.

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/knowledge-base-articles" \
	--data-raw '
		{
			"articleBody": "Foo",
			"title": "Able"
		}' \
	--header "Content-Type: application/json" \
	--request "POST" \
	--user "test@liferay.com:learn"

Here are the command’s arguments:

Arguments	Description
`-H "Content-Type: application/json"`	Indicates that the request body format is JSON.
`-X POST`	The HTTP method to invoke at the specified endpoint
`"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/knowledge-base-articles"`	The REST service endpoint
`-d "{\"articleBody\": \"Foo\", \"title\": \"Able\"}"`	The data you are requesting to post
`-u "test@liferay.com:learn"`	Basic authentication credentials

Note

Basic authentication is used for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.

The other cURL commands use similar JSON arguments.

Examine the Java Class

The KnowledgeBaseArticles_POST_ToSite.java class adds a Knowledge Base article by calling the KnowledgeBaseArticleResource service.

public static void main(String[] args) throws Exception {
	KnowledgeBaseArticleResource.Builder builder =
		KnowledgeBaseArticleResource.builder();

	KnowledgeBaseArticleResource knowledgeBaseArticleResource =
		builder.authentication(
			"test@liferay.com", "learn"
		).build();

	KnowledgeBaseArticle knowledgeBaseArticle =
		knowledgeBaseArticleResource.postSiteKnowledgeBaseArticle(
			Long.valueOf(System.getProperty("siteId")),
			new KnowledgeBaseArticle() {
				{
					articleBody = "Foo";
					title = "Charlie";
				}
			});

	System.out.println(knowledgeBaseArticle);
}

This class invokes the REST service using only three lines of code:

Line (abbreviated)	Description
`KnowledgeBaseArticleResource.Builder builder = ...`	Gets a `Builder` for generating an `KnowledgeBaseArticleResource` service instance.
`KnowledgeBaseArticleGroupResource knowledgeBaseArticleGroupResource = builder.authentication(...).build();`	Specifies basic authentication and generates a `KnowledgeBaseArticleResource` service instance.
`KnowledgeBaseArticle knowledgeBaseArticle = knowledgeBaseArticleResource.postSiteKnowledgeBaseArticle(...);`	Calls the `knowledgeBaseArticleResource.postSiteKnowledgeBaseArticle` method and passes the data to post.

Note that the project includes the com.liferay.headless.delivery.client.jar file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different KnowledgeBaseArticle methods.

Important

See KnowledgeBaseArticleResource for service details.

Below are examples of calling other