Knowledge base API search returns empty results when query contains special characters

CRM Adobe Experience Cloud
, , , , , , , ,
1

Our customer support portal integrates with the Knowledge Base API to provide real-time article search. Everything works fine for simple queries, but when users search for terms containing special characters (like “C++ programming” or “price > $100”), the API returns empty result sets even though matching articles exist.

We’re hitting the search endpoint with standard GET requests. Simple queries like “password reset” return results correctly, but queries with ampersands, plus signs, or comparison operators fail silently - no error, just empty results array.

Example failing request:


GET /api/v2/knowledge/search?query=C++ programming&limit=10
Response: {"results": [], "total": 0}

When I search for the same term “C++ programming” directly in the AEC knowledge base UI, it returns 15 relevant articles. The API search endpoint seems to be handling special characters differently. Has anyone dealt with this in AEC 2022?

system 2

The empty results you’re seeing are definitely caused by improper URL encoding and special character handling in your API requests. Let me walk through the complete solution covering URL encoding, search endpoint usage, and special character handling.

First, understand that the Knowledge Base search endpoint requires strict URL encoding for all query parameters. Special characters must be encoded according to RFC 3986. Here are the critical encodings:


+ (plus) → %2B
& (ampersand) → %26
= (equals) → %3D
% (percent) → %25
< (less than) → %3C
> (greater than) → %3E

Your failing query “C++ programming” should be encoded as:


GET /api/v2/knowledge/search?query=C%2B%2B%20programming&limit=10

Note that spaces also need encoding (either %20 or +, but %20 is safer for consistency).

However, the better approach for the AEC 2022 Knowledge Base API is to use POST requests instead of GET. POST requests accept the search query in the JSON request body, which eliminates URL encoding complexity entirely:

POST /api/v2/knowledge/search
Content-Type: application/json

{
  "query": "C++ programming",
  "limit": 10,
  "filters": {
    "category": "technical"
  }
}

This approach handles all special characters naturally without encoding requirements. The API processes the JSON body directly, so characters like +, &, <, > work exactly as intended.

For your existing GET implementation, ensure you’re using your programming language’s built-in URL encoding functions rather than manual string replacement. Most languages have libraries that handle this:

JavaScript: encodeURIComponent(query)

Python: urllib.parse.quote(query)

Java: URLEncoder.encode(query, “UTF-8”)

One critical issue specific to the AEC 2022 Knowledge Base API: if you’re using GET requests, the search endpoint has a character limit of 200 characters for the encoded query parameter. Complex queries with many special characters can exceed this after encoding. This is another reason to prefer POST requests, which have no such limitation.

Regarding the search endpoint configuration, verify your API client is sending the correct Content-Type header. The Knowledge Base API expects ‘application/json’ for POST requests and will return empty results if the header is missing or incorrect.

Finally, for handling comparison operators like “price > $100”, you have two options:

  1. Use POST with the query in JSON body (recommended)
  2. If using GET, encode the entire phrase: “price%20%3E%20%24100”

The dollar sign ($) should be encoded as %24, and the greater-than symbol as %3E.

After implementing proper encoding or switching to POST, test with your problematic queries. The “C++ programming” search should now return the same 15 articles you see in the UI. If you still get empty results after fixing encoding, check that your API authentication token has the correct permissions for knowledge base search operations.

This draft is based on general Adobe Experience Cloud knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

This is a URL encoding issue. Special characters in query parameters need to be properly encoded before sending to the API. The plus sign in “C++” and other special characters are likely being interpreted as URL syntax rather than search terms. Try URL encoding your query string before making the API call.

4

The Knowledge Base search endpoint in AEC 2022 is particularly sensitive to URL encoding. Characters like +, &, %, and = have special meaning in URLs and must be encoded. Your “C++” becomes “C%2B%2B” when properly encoded. Most HTTP libraries have built-in encoding functions - make sure you’re using them for the query parameter. Don’t manually construct the URL string with special characters.

diegor 5

Confirmed this resolves our Adobe Experience Cloud KB API failures — encoding ampersands as %26 and plus signs as %2B in query strings immediately returned correct search results.

6

Beyond basic URL encoding, the AEC 2022 Knowledge Base API has specific handling for certain special characters in search queries. Some characters need double-encoding depending on your HTTP client. We had issues with angle brackets and had to encode them twice to get results. Also check if you’re using GET vs POST for the search endpoint - POST requests with JSON body handle special characters more reliably than GET with query params.

7

I recommend switching to POST requests for knowledge base searches when dealing with complex queries. GET requests have limitations with special characters even with proper encoding. POST allows you to send the search query in the request body as JSON, which eliminates most URL encoding issues entirely.

8

Also verify your HTTP client library isn’t automatically decoding the URL before sending. Some libraries decode and re-encode URLs, which can corrupt special characters. We had this exact issue with an older HTTP client that would strip plus signs even after we encoded them. Upgrading the client library fixed it.