# URL Management

URL mapping query and dynamic resolution

## Query URL mappings with dynamic resolution

> Returns stored URL mappings matching the query criteria. When no stored mapping exists, automatically performs dynamic resolution by analyzing the application's routing configuration.\
> \
> \*\*Query Strategies:\*\*\
> \
> \*\*1. Path-Based Query\*\* (\`new\_path\` or \`old\_path\` parameter)\
> \* Searches stored mappings first\
> \* If not found, activates dynamic resolution\
> \* Returns view metadata, route parameters, and query strings\
> \* Suitable for navigation and redirection logic\
> \
> \*\*2. Unified Path Query\*\* (\`path\` parameter)\
> \* Searches \`new\_path\` field first, then falls back to \`old\_path\`\
> \* Automatically tries both path formats in sequence\
> \
> \*\*3. Product-Specific Redirection\*\* (\`path\` parameter with product ID format)\
> \* Detects product ID patterns (e.g., \`/product/123/\`)\
> \* Automatically resolves to sibling product URL when original is unavailable\
> \* Returns HTTP redirect response instead of JSON\
> \* Used for maintaining product navigation when items are delisted\
> \
> \*\*4. Advanced Filtering\*\* (multiple filter parameters)\
> \* Combine language, parent, and date range filters\
> \* Returns paginated list of stored mappings only\
> \
> \*\*Dynamic Resolution Details:\*\*\
> \
> When a path query returns zero stored results, the system:\
> 1\. Parses the URL to separate path and query components\
> 2\. Resolves the path through the application routing engine\
> 3\. Extracts view module, function name, and initialization parameters\
> 4\. Captures route arguments, keyword arguments, and query parameters\
> 5\. Returns a synthesized response with all routing metadata\
> \
> This ensures navigation never fails for valid application URLs, even if they haven't been explicitly stored in the URL registry.

````json
{"openapi":"3.1.0","info":{"title":"Pretty URLs API - URL Management & Dynamic Resolution","version":"1.0.0"},"tags":[{"name":"URL Management","description":"URL mapping query and dynamic resolution"}],"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/pretty_urls/":{"get":{"tags":["URL Management"],"operationId":"listPrettyUrls","summary":"Query URL mappings with dynamic resolution","description":"Returns stored URL mappings matching the query criteria. When no stored mapping exists, automatically performs dynamic resolution by analyzing the application's routing configuration.\n\n**Query Strategies:**\n\n**1. Path-Based Query** (`new_path` or `old_path` parameter)\n* Searches stored mappings first\n* If not found, activates dynamic resolution\n* Returns view metadata, route parameters, and query strings\n* Suitable for navigation and redirection logic\n\n**2. Unified Path Query** (`path` parameter)\n* Searches `new_path` field first, then falls back to `old_path`\n* Automatically tries both path formats in sequence\n\n**3. Product-Specific Redirection** (`path` parameter with product ID format)\n* Detects product ID patterns (e.g., `/product/123/`)\n* Automatically resolves to sibling product URL when original is unavailable\n* Returns HTTP redirect response instead of JSON\n* Used for maintaining product navigation when items are delisted\n\n**4. Advanced Filtering** (multiple filter parameters)\n* Combine language, parent, and date range filters\n* Returns paginated list of stored mappings only\n\n**Dynamic Resolution Details:**\n\nWhen a path query returns zero stored results, the system:\n1. Parses the URL to separate path and query components\n2. Resolves the path through the application routing engine\n3. Extracts view module, function name, and initialization parameters\n4. Captures route arguments, keyword arguments, and query parameters\n5. Returns a synthesized response with all routing metadata\n\nThis ensures navigation never fails for valid application URLs, even if they haven't been explicitly stored in the URL registry.","parameters":[{"name":"new_path","in":"query","description":"Filter by the display URL path (human-readable, SEO-friendly format).\n\n**Query Behavior:**\n* Searches the `new_path` field for exact matches\n* If no stored mapping found, triggers dynamic resolution\n* Path is automatically normalized (leading/trailing slashes added based on configuration)\n\n**Example Values:**\n* `/products/shoes/running-shoes/`\n* `/categories/electronics/`\n* `/special-offers/`\n\n**Dynamic Resolution Example:**\nIf you query `/products/new-arrival/` and no stored mapping exists, the system will resolve it through the routing engine and return view metadata for that path.","required":false,"schema":{"type":"string","format":"uri-reference"}},{"name":"old_path","in":"query","description":"Filter by the canonical URL path (original application route).\n\n**Query Behavior:**\n* Searches the `old_path` field for exact matches\n* If no stored mapping found, triggers dynamic resolution\n* Typically represents the internal application route before prettification\n\n**Example Values:**\n* `/product-detail/123/`\n* `/category/45/`\n* `/cms/page/about-us/`\n\n**Use Case:**\nQuery old paths when you need to find what pretty URL maps to a specific internal route, or when resolving legacy URLs after a site migration.","required":false,"schema":{"type":"string","format":"uri-reference"}},{"name":"path","in":"query","description":"Unified path search that checks both display and canonical paths.\n\n**Search Order:**\n1. First searches `new_path` field\n2. If no match, searches `old_path` field\n3. If still no match, triggers dynamic resolution\n\n**Special Behavior - Product Redirection:**\nWhen the path matches a product URL pattern (contains \"product\" keyword and numeric ID), the system attempts to redirect to a sibling product if the original is unavailable. This returns an HTTP 302 redirect response instead of JSON.\n\n**Example Values:**\n* `/products/shoes/` (standard path)\n* `/product/456/` (triggers product redirection logic)\n* `/category/electronics/` (standard path)\n\n**Convenience Use Case:**\nUse this parameter when you don't know whether the path is stored as a pretty URL or canonical URL. The system will automatically try both.","required":false,"schema":{"type":"string","format":"uri-reference"}},{"name":"new_path__exact","in":"query","description":"Performs an exact match search on the display URL path.\n\n**Difference from `new_path`:**\n* Does NOT trigger dynamic resolution if no match found\n* Returns empty results when no stored mapping exists\n* Useful for checking if a specific pretty URL is already registered\n\n**Use Case:**\nUse this when you want to verify the existence of a stored mapping without triggering fallback resolution, such as during URL uniqueness validation or administrative checks.","required":false,"schema":{"type":"string","format":"uri-reference"}},{"name":"language","in":"query","description":"Filter by language code for multi-language URL mappings.\n\n**Behavior:**\n* Returns only URLs assigned to the specified language\n* Supports standard language codes (e.g., `en`, `tr`, `ar`, `de`)\n* Null language values represent language-neutral URLs\n\n**Multi-Language Configuration:**\nWhen multi-language mode is enabled *(Source: Static System Configuration)*, each URL can have language-specific variants stored as child mappings. Parent URLs typically have a default or null language value.\n\n**Example Values:**\n* `en` - English\n* `tr` - Turkish  \n* `ar` - Arabic\n* `de` - German\n\n**Use Case:**\nEssential for international storefronts where the same logical page has different URL paths per language for SEO optimization.","required":false,"schema":{"type":"string","minLength":2,"maxLength":10}},{"name":"parent","in":"query","description":"Filter by parent URL identifier for hierarchical URL structures.\n\n**Hierarchy Model:**\n* Parent URLs represent the primary, language-neutral mapping\n* Child URLs (via `prettyurl_set`) represent language-specific variants\n* Top-level URLs have `parent=null`\n\n**Query Options:**\n* Provide a parent ID to find all child language variants\n* Omit to include all URL levels in results\n* Combine with `language` filter to find specific language variants of a parent\n\n**Example:**\nIf parent URL `/products/shoes/` has ID `42`, querying `parent=42` returns all language-specific child URLs like `/tr/urunler/ayakkabi/`, `/ar/منتجات/أحذية/`, etc.\n\n**Use Case:**\nNavigate URL hierarchies when managing multi-language content or discovering all language variants of a specific page.","required":false,"schema":{"type":"integer"}},{"name":"created_date__gt","in":"query","description":"Filter URLs created after the specified datetime (exclusive).\n\n**Format:** ISO 8601 datetime with timezone\n**Example:** `2024-01-01T00:00:00Z`\n\nReturns only stored mappings created after this timestamp. Useful for tracking recently added URLs or monitoring URL generation activities.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_date__gte","in":"query","description":"Filter URLs created on or after the specified datetime (inclusive).\n\n**Format:** ISO 8601 datetime with timezone\n**Example:** `2024-01-01T00:00:00Z`\n\nReturns stored mappings created at or after this timestamp. Useful for date-range queries and reporting.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_date__lt","in":"query","description":"Filter URLs created before the specified datetime (exclusive).\n\n**Format:** ISO 8601 datetime with timezone\n**Example:** `2024-12-31T23:59:59Z`\n\nReturns only stored mappings created before this timestamp. Useful for historical analysis or finding legacy URLs.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"created_date__lte","in":"query","description":"Filter URLs created on or before the specified datetime (inclusive).\n\n**Format:** ISO 8601 datetime with timezone\n**Example:** `2024-12-31T23:59:59Z`\n\nReturns stored mappings created at or before this timestamp. Completes date-range query capabilities.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_date__gt","in":"query","description":"Filter URLs modified after the specified datetime (exclusive).\n\n**Format:** ISO 8601 datetime with timezone\n\nReturns only stored mappings updated after this timestamp. Essential for tracking URL changes and synchronization activities.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_date__gte","in":"query","description":"Filter URLs modified on or after the specified datetime (inclusive).\n\n**Format:** ISO 8601 datetime with timezone\n\nReturns stored mappings updated at or after this timestamp.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_date__lt","in":"query","description":"Filter URLs modified before the specified datetime (exclusive).\n\n**Format:** ISO 8601 datetime with timezone\n\nReturns only stored mappings updated before this timestamp.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"modified_date__lte","in":"query","description":"Filter URLs modified on or before the specified datetime (inclusive).\n\n**Format:** ISO 8601 datetime with timezone\n\nReturns stored mappings updated at or before this timestamp.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"page","in":"query","description":"Page number for paginated results.\n\n**Default:** 1 (first page)\n**Behavior:** Returns the specified page of results based on the configured page size\n\nPagination applies only to stored mappings. Dynamic resolution always returns a single result (count=1).","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"page_size","in":"query","description":"Number of items per page.\n\n**Limits:** Subject to system-configured maximum page size\n**Default:** Determined by pagination configuration (typically 10)\n\nAllows clients to control result density. Larger page sizes reduce request count but increase response size.","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Successfully retrieved URL mappings or performed dynamic resolution.\n\n**Response Types:**\n\n**1. Stored Mappings Found** (count > 0)\n* Contains database records with all metadata\n* Includes timestamps (`created_date`, `modified_date`)\n* May include hierarchical relationships (parent and child URLs)\n* Paginated when multiple results exist\n\n**2. Dynamic Resolution Performed** (count = 1, timestamps null)\n* Contains synthesized routing information\n* `created_date` and `modified_date` are `null`\n* `pk` is absent (no database identifier)\n* Single result with resolved view metadata\n\n**3. No Results** (count = 0)\n* Occurs when using advanced filters without path parameters\n* Indicates no stored mappings match the criteria\n* Empty `results` array\n\n**Pagination Notes:**\n* `next`: URL to retrieve the next page (null if on last page)\n* `previous`: URL to retrieve the previous page (null if on first page)\n* `count`: Total number of matching URLs across all pages","content":{"application/json":{"schema":{"type":"object","required":["count","next","previous","results"],"properties":{"count":{"type":"integer","description":"Total number of URL mappings matching the query. A value of 1 with null timestamps indicates dynamic resolution was performed."},"next":{"type":"string","format":"uri","nullable":true,"description":"URL to fetch the next page of results. Null when on the last page or when count <= page_size."},"previous":{"type":"string","format":"uri","nullable":true,"description":"URL to fetch the previous page of results. Null when on the first page."},"results":{"type":"array","description":"Array of URL mapping objects. Contains stored database records or dynamically resolved routing information.","items":{"$ref":"#/components/schemas/PrettyUrl"}}}}}}},"302":{"description":"Redirect to sibling product URL.\n\n**Trigger Condition:**\nWhen querying with the `path` parameter containing a product ID format (e.g., `/product/123/`) and the system determines the original product is unavailable.\n\n**Redirection Logic:**\n1. Extracts product ID from the path\n2. Loads the product record\n3. Checks product type and availability status\n4. Selects an appropriate sibling or parent product\n5. Returns HTTP 302 redirect to the new product's URL\n\n**Product Type Handling:**\n* **Simple Products:** Redirects to parent product if available\n* **Parent Products:** Redirects to first listable variant\n* Falls back to 404 if no suitable sibling exists\n\n**Configuration:**\nThis behavior can be enabled or disabled at runtime *(Source: Dynamic/Real-time Configuration)* to control whether unavailable products redirect to alternatives or return errors.","headers":{"Location":{"description":"The URL of the sibling product to redirect to","schema":{"type":"string","format":"uri"}}}},"404":{"description":"URL path could not be resolved.\n\n**Occurrence Scenarios:**\n\n**1. Invalid Application Route:**\nThe provided path does not match any configured application route and cannot be resolved dynamically. This indicates the path is not a valid application URL.\n\n**2. Product Redirection Failed:**\nWhen using the `path` parameter with product ID format, the product was not found or has no available siblings to redirect to.\n\n**Distinction from 200 with count=0:**\n* 404: The path itself is invalid or unresolvable\n* 200 with count=0: The path is valid but no stored mapping exists, or filters excluded all results","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PrettyUrl":{"type":"object","description":"Represents a URL mapping with complete routing metadata.\n\n**Database Records vs. Dynamic Resolution:**\n\n* **Stored Mappings:** Include `pk`, `created_date`, `modified_date`, and may have hierarchical relationships\n* **Dynamic Resolutions:** Have null timestamps, no `pk` field, and empty `prettyurl_set`\n\n**Field Purposes:**\n\n* **Path Fields:** Define the URL transformation (pretty vs. canonical)\n* **View Metadata:** Enable route resolution (`func_module`, `func_name`, `func_initkwargs`)\n* **Route Parameters:** Capture dynamic URL segments (`args`, `kwargs`)\n* **Query Data:** Preserve URL query parameters for full route reconstruction\n* **Hierarchy:** Support multi-language variants through parent-child relationships","properties":{"pk":{"type":"integer","description":"Unique identifier for stored URL mappings.\n\n**Presence Rules:**\n* Present in database-stored mappings\n* Absent in dynamically resolved results\n* Used for referencing parent URLs in hierarchical structures\n\nClients should check for this field to distinguish between stored and resolved URLs.","nullable":false},"new_path":{"type":"string","format":"uri-reference","description":"The display URL path shown to users and search engines.\n\n**Characteristics:**\n* Human-readable, SEO-optimized format\n* Automatically normalized with leading and trailing slashes based on configuration *(Source: Static System Configuration)*\n* Must be unique across the system\n* Cannot be `/` (root path is reserved)\n\n**Multi-Language Behavior:**\nWhen multi-language mode is enabled *(Source: Static System Configuration)*, language-specific paths may include language prefixes based on the runtime configuration *(Source: Dynamic/Real-time Configuration)*.\n\n**Validation:**\n* Must differ from `old_path` (cannot prettify a URL to itself)\n* Automatically URL-encoded\n* Maximum length: 512 characters","nullable":false},"old_path":{"type":"string","format":"uri-reference","description":"The canonical application route this pretty URL maps to.\n\n**Purpose:**\n* Represents the internal application path before prettification\n* Used for reverse lookups when resolving internal routes\n* Automatically normalized with leading and trailing slashes *(Source: Static System Configuration)*\n\n**Relationship to `new_path`:**\nMultiple pretty URLs (new_path) can point to the same canonical URL (old_path), enabling URL aliasing and A/B testing of URL structures.\n\n**Nullability:**\n* Required when creating manual mappings\n* May be null in rare legacy cases\n* Always present in API responses","nullable":true},"parent":{"type":"integer","nullable":true,"description":"Reference to the parent URL identifier for hierarchical URL structures.\n\n**Hierarchy Rules:**\n* Null for top-level, language-neutral URLs\n* Contains parent `pk` value for language-specific child URLs\n* Enables one-to-many relationship (one parent, multiple children)\n\n**Multi-Language Architecture:**\nParent URLs serve as the canonical reference, while child URLs in `prettyurl_set` provide language-specific variants. This structure allows the same logical page to have different URL paths per language.\n\n**Example:**\nA parent URL `/products/shoes/` (parent=null) might have children like `/tr/urunler/ayakkabi/` (parent=42) and `/ar/منتجات/أحذية/` (parent=42)."},"language":{"type":"string","nullable":true,"description":"Language code for multi-language URL variants.\n\n**Format:** ISO 639-1 language codes (2-character) or extended codes (up to 10 characters)\n**Examples:** `en`, `tr`, `ar`, `de`, `en-US`, `zh-CN`\n\n**Hierarchy Relationship:**\n* Parent URLs typically have `null` or default language\n* Child URLs in `prettyurl_set` have specific language codes\n* Language assignment is required when multi-language mode is enabled *(Source: Static System Configuration)*\n\n**Nullability:**\n* Null for language-neutral URLs in single-language configurations\n* Null or default language for parent URLs in multi-language setups\n* Specific language code for child URLs\n\n**Use Case:**\nEssential for serving localized content and SEO optimization in international markets where the same page needs different URLs per language.","minLength":2,"maxLength":10},"func_module":{"type":"string","nullable":true,"description":"Python module path of the view handling this URL.\n\n**Format:** Dot-separated module path (e.g., `omnishop.products.views`)\n\n**Purpose:**\n* Identifies the application component responsible for rendering this URL\n* Enables programmatic view resolution\n* Used internally for route reconstruction\n\n**Common Patterns:**\n* Product pages: `omnishop.products.views`\n* Category pages: `omnishop.catalogs.views`\n* CMS pages: `omnishop.cms.views`\n* Static pages: `django.views.generic`\n\nThis metadata enables the system to reconstruct the full view context for any URL.","maxLength":256},"func_name":{"type":"string","nullable":true,"description":"View class or function name handling this URL.\n\n**Format:** Python class or function identifier\n\n**Purpose:**\n* Specifies the exact view component within `func_module`\n* Combined with `func_module`, creates a complete view reference\n* Essential for route resolution and URL reversal\n\n**Common Examples:**\n* `ProductDetailView` - Individual product pages\n* `CategoryListView` - Category browsing\n* `FlatPageView` - Static CMS content\n* `CheckoutView` - Checkout process\n\nTogether with `func_module` and `func_initkwargs`, this provides complete view instantiation information.","maxLength":64},"func_initkwargs":{"type":"object","description":"View initialization parameters passed when instantiating the view.\n\n**Structure:** JSON object with key-value pairs\n\n**Purpose:**\n* Configures view-specific behavior\n* Passes template names, model references, or custom parameters\n* Enables view customization without code changes\n\n**Common Parameters:**\n* `model`: Model class name for generic views\n* `template_name`: Template file path\n* `slug_field`: Field used for slug-based lookups\n* Custom business logic parameters\n\n**Example:**\n```json\n{\n  \"model\": \"Product\",\n  \"template_name\": \"products/detail.html\"\n}\n```\n\nThis allows the same view class to handle different contexts based on initialization parameters.","additionalProperties":true},"args":{"type":"array","description":"Positional route parameters extracted from the URL path.\n\n**Format:** Array of strings representing captured URL segments\n\n**Purpose:**\n* Captures unnamed URL path parameters\n* Maintains parameter order from URL pattern\n* Passed to view as positional arguments\n\n**Usage Pattern:**\nModern applications typically use keyword arguments (`kwargs`) instead of positional arguments for clarity and maintainability. This field is often empty in contemporary URL configurations.\n\n**Example:**\nFor a URL pattern like `/archive/<year>/<month>/`, args might be `[\"2024\", \"11\"]`.","items":{"type":"string","maxLength":32}},"kwargs":{"type":"object","description":"Named route parameters extracted from the URL path.\n\n**Structure:** JSON object mapping parameter names to values\n\n**Purpose:**\n* Captures named URL path segments defined in route patterns\n* Provides semantic parameter names for view logic\n* Enables type-safe parameter passing\n\n**Common Parameters:**\n* `pk` or `id`: Primary key for database lookups\n* `slug`: URL-friendly identifier\n* `category_id`, `product_id`: Entity identifiers\n* `page_slug`, `section`: Content navigation parameters\n\n**Example:**\nFor URL pattern `/products/<slug:slug>/`, kwargs would be `{\"slug\": \"running-shoes\"}`.\n\nThis is the preferred method for passing URL parameters in modern applications due to improved code readability.","additionalProperties":{"type":"string"}},"query_params":{"type":"object","description":"Query string parameters parsed from the URL.\n\n**Structure:** JSON object mapping parameter names to values\n\n**Purpose:**\n* Preserves URL query strings (everything after `?`)\n* Supports filtering, sorting, and pagination parameters\n* Maintains analytics tracking parameters (UTM codes, etc.)\n\n**Common Use Cases:**\n* **Filtering:** `?color=red&size=large`\n* **Pagination:** `?page=2&page_size=20`\n* **Sorting:** `?sort=price&order=asc`\n* **Tracking:** `?utm_source=email&utm_campaign=summer2024`\n* **Search:** `?q=running+shoes`\n\n**Preservation:**\nQuery parameters are maintained separately from path parameters, allowing full URL reconstruction including all query data.\n\n**Example:**\nFor URL `/products/?category=shoes&color=blue`, query_params would be `{\"category\": \"shoes\", \"color\": \"blue\"}`.","additionalProperties":{"type":"string"}},"viewname":{"type":"string","nullable":true,"description":"Named URL pattern identifier for reverse URL resolution.\n\n**Purpose:**\n* Enables programmatic URL generation using Django's `reverse()` functionality\n* Provides a stable identifier for URL patterns independent of path structure\n* Facilitates URL construction in templates and code\n\n**Format:** Kebab-case or snake_case identifier\n\n**Common Examples:**\n* `product-detail` - Product detail pages\n* `category-list` - Category browsing\n* `checkout` - Checkout process\n* `cms-flatpage` - Static CMS pages\n\n**Reverse Resolution:**\nApplications can generate URLs by calling `reverse('product-detail', kwargs={'pk': 456})` instead of hardcoding paths, ensuring URL changes don't break application code.\n\nThis field bridges the gap between human-readable URLs and programmatic route management.","maxLength":64},"created_date":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when this URL mapping was first created.\n\n**Format:** ISO 8601 datetime with timezone\n**Example:** `2024-11-15T10:30:00Z`\n\n**Presence Rules:**\n* Present with valid timestamp for database-stored mappings\n* Null for dynamically resolved URLs (not stored in database)\n\n**Use Cases:**\n* Audit trail for URL creation\n* Identifying recently added URLs\n* Tracking URL generation activities\n* Monitoring URL registry growth\n\nClients can use null values to detect dynamically resolved results vs. stored mappings."},"modified_date":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when this URL mapping was last updated.\n\n**Format:** ISO 8601 datetime with timezone\n**Example:** `2024-11-20T14:22:00Z`\n\n**Presence Rules:**\n* Present with valid timestamp for database-stored mappings\n* Null for dynamically resolved URLs (not stored in database)\n* Updated whenever any field in the mapping changes\n\n**Use Cases:**\n* Tracking URL changes and updates\n* Cache invalidation triggers\n* Synchronization activities\n* URL audit logs\n\nCompare `modified_date` with `created_date` to identify URLs that have been edited post-creation."},"prettyurl_set":{"type":"array","description":"Child URL mappings for multi-language variants.\n\n**Structure:** Array of language-specific URL objects\n\n**Purpose:**\n* Stores language-specific URL paths for the same logical page\n* Enables internationalized SEO with localized URLs\n* Maintains parent-child hierarchy for URL organization\n\n**Population Rules:**\n* Empty array when multi-language mode is disabled *(Source: Static System Configuration)*\n* Empty for dynamically resolved URLs (no stored children)\n* Empty for child URLs themselves (prevents nesting beyond one level)\n* Populated for parent URLs when language-specific mappings exist\n\n**Child Object Structure:**\nEach child contains `pk`, `new_path`, and `language` fields. Children inherit routing metadata from their parent, so they don't duplicate `func_module`, `func_name`, etc.\n\n**Example:**\nA parent English URL `/products/shoes/` might have children:\n* Turkish: `/tr/urunler/ayakkabi/`\n* Arabic: `/ar/منتجات/أحذية/`\n* German: `/de/produkte/schuhe/`\n\nThis architecture enables one database record to manage multiple language-specific URLs.","items":{"$ref":"#/components/schemas/ChildPrettyUrl"}}}},"ChildPrettyUrl":{"type":"object","description":"Represents a language-specific URL variant within a multi-language hierarchy.\n\n**Hierarchy Position:**\n* Always a child of a parent URL (never standalone)\n* Inherits routing metadata from parent\n* Only contains fields necessary for language-specific identification\n\n**Simplified Structure:**\nChild objects include only `pk`, `new_path`, and `language` since they share routing metadata with their parent.","required":["pk","new_path","language"],"properties":{"pk":{"type":"integer","description":"Unique identifier for this language-specific URL variant.\n\nUsed for direct lookup and parent relationship management."},"new_path":{"type":"string","format":"uri-reference","description":"The language-specific display URL path.\n\n**Localization:**\n* Contains translated or transliterated URL segments\n* Follows language-specific URL conventions\n* May include language prefix based on configuration *(Source: Dynamic/Real-time Configuration)*\n\n**Examples:**\n* English: `/products/running-shoes/`\n* Turkish: `/tr/urunler/kosu-ayakkabilari/`\n* Arabic: `/ar/منتجات/أحذية-الجري/`\n* German: `/de/produkte/laufschuhe/`\n\nEach language variant points to the same logical page but uses localized URL text for SEO optimization.","maxLength":512},"language":{"type":"string","description":"Language code for this URL variant.\n\n**Format:** ISO 639-1 language codes (2-character) or extended codes\n**Examples:** `en`, `tr`, `ar`, `de`, `en-US`, `zh-CN`\n\n**Requirements:**\n* Must be non-null for child URLs\n* Must correspond to a configured system language\n* Should match the localization of the `new_path` content\n\nThis field enables language-aware routing and content delivery.","minLength":2,"maxLength":10}}}}}}
````


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.akinon.com/commerce-openapis/pretty-urls/url-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.