{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"URL Encoding of Query Parameters","description":"API documentation for Celonis APIs.","siteUrl":"https://developer.celonis.com/","keywords":"celonis developer portal, celonis apis, celonis api reference docs","lang":"en-US","llmstxt":{"hide":false,"description":"Celonis API documentation","sections":[{"title":"API Docs","description":"Available Celonis API Docs","includeFiles":["**/*.md"],"excludeFiles":[]},{"title":"API Specs","description":"All Celonis API specifications","includeFiles":["**/openapi.yaml"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"url-encoding-of-query-parameters","__idx":0},"children":["URL Encoding of Query Parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When building GET API requests, query parameter values may contain special characters such as spaces, &, =, ?, (, ), *, %, and others."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These characters have specific meanings in URLs and can lead to incorrect request parsing if not properly encoded."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-encoding-is-important","__idx":1},"children":["Why encoding is important"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["URL encoding ensures that special characters are safely transmitted and correctly interpreted by the API."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Encode only the query parameter values, not the entire URL."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"common-characters-and-their-encoded-forms","__idx":2},"children":["Common characters and their encoded forms"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Character"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["URL Encoded Form"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["space"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%20"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%27"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\""]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%22"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%26"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["("]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%28"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":[")"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%29"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["*"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%2A"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%25"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["="]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%3D"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"incorrect-example","__idx":3},"children":["Incorrect Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /intelligence/api/knowledge-models/km_id/data?filterExpr=status eq 'active' and department eq 'Sales & Marketing' and name eq 'John'\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This fails because ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]}," acts as a parameter separator"]}," and spaces must be URL-encoded."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"correct-example","__idx":4},"children":["Correct Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"GET /intelligence/api/knowledge-models/km_id/data?filterExpr=status%20eq%20%27active%27%20and%20department%20eq%20%27Sales%20%26%20Marketing%27%20and%20name%20eq%20%27John%27\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr"]}," value is URL-encoded:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Spaces → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%20"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]}," (ampersand) → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%26"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["'"]}," (single quote) → ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%27"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Without encoding, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["&"]}," would be interpreted as a separator between query parameters, breaking the request. Encoding ensures that all characters are correctly interpreted as part of the filter expression."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"encoding-in-your-code","__idx":5},"children":["Encoding in your code"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use built-in URL encoding functions to ensure correct formatting of query parameter values."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most programming languages provide built-in functions for URL encoding. The following examples show how to encode a string value before adding it to a request URL."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Depending on the encoder, spaces may be encoded as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["%20"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["+"]},". Both are valid in query strings."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"javascript","__idx":6},"children":["JavaScript"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["encodeURIComponent()"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"const filter = \"name eq 'Sales & Marketing'\";\nconst encodedFilter = encodeURIComponent(filter);\n\n// Encoded result:\n// name%20eq%20%27Sales%20%26%20Marketing%27\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"python","__idx":7},"children":["Python"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["urllib.parse.quote()"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","header":{"controls":{"copy":{}}},"source":"from urllib.parse import quote\n\nfilter = \"name eq 'Sales & Marketing'\"\nencoded_filter = quote(filter)\n\n// Encoded result:\n// name%20eq%20%27Sales%20%26%20Marketing%27\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"java","__idx":8},"children":["Java"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["URLEncoder.encode()"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"import java.net.URLEncoder;\nimport java.nio.charset.StandardCharsets;\n\nString filter = \"name eq 'Sales & Marketing'\";\nString encodedFilter = URLEncoder.encode(filter, StandardCharsets.UTF_8);\n\n// Encoded result:\n// name+eq+%27Sales+%26+Marketing%27\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"c","__idx":9},"children":["C#"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["HttpUtility.UrlEncode()"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["System.Web"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WebUtility.UrlEncode()"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["System.Net"]},"."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"csharp","header":{"controls":{"copy":{}}},"source":"using System.Net;\n\nstring filter = \"name eq 'Sales & Marketing'\";\nstring encodedFilter = WebUtility.UrlEncode(filter);\n\n// Encoded result:\n// name+eq+%27Sales+%26+Marketing%27\n","lang":"csharp"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For quick tests, you can also use online URL encoder/decoder tools."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"optional-use-openapi-generated-clients","__idx":10},"children":["Optional: Use OpenAPI-generated clients"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you are using an OpenAPI-generated client, query parameter encoding is typically handled automatically by the generated code or the underlying HTTP library."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this case, you can pass the raw filter expression as a parameter filter, without manually encoding it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example","__idx":11},"children":["Example:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filterExpr"]},": \"name eq 'Sales & Marketing'\""]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See available generators:"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://openapi-generator.tech/docs/generators/"},"children":["https://openapi-generator.tech/docs/generators/"]}]}]},"headings":[{"value":"URL Encoding of Query Parameters","id":"url-encoding-of-query-parameters","depth":2},{"value":"Why encoding is important","id":"why-encoding-is-important","depth":2},{"value":"Common characters and their encoded forms","id":"common-characters-and-their-encoded-forms","depth":3},{"value":"Incorrect Example","id":"incorrect-example","depth":3},{"value":"Correct Example","id":"correct-example","depth":3},{"value":"Encoding in your code","id":"encoding-in-your-code","depth":2},{"value":"JavaScript","id":"javascript","depth":3},{"value":"Python","id":"python","depth":3},{"value":"Java","id":"java","depth":3},{"value":"C#","id":"c","depth":3},{"value":"Optional: Use OpenAPI-generated clients","id":"optional-use-openapi-generated-clients","depth":3},{"value":"Example:","id":"example","depth":4}],"frontmatter":{"seo":{"title":"URL Encoding of Query Parameters"}},"lastModified":"2026-04-27T14:18:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/process-intelligence-apis/knowledge-model-api/features/url-encoding","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}