--- title: "Service: /uri/{uri} [GET]" source: https://dev.pageseeder.com/api/services/default-GET.html description: "GET service for retrieving PageSeeder documents and files by URI ID, DocID, or path. Supports version comparison, publication context, transclusion, and caching. Returns native content or PSML metadata." last_updated: 2026-08-11T16:37:30+10:00 document_type: api_endpoint operation_id: uri-GET resource_id: uri path_template: /uri/{uri} http_method: GET api_category: uri implementation_version: 6.2000 api_since: 3.1001 deprecated_since: null obsolete_since: null api_support: supported cache_control: null generated_at: 2025-08-04 tokens: ~5932 --- # /uri/\{uri\} \[GET\] ## Description This service accepts GET, HEAD or OPTIONS requests for a file (document) stored on PageSeeder, checks access permission and fetches the file. > **Note:**  This service does not use the `/api` prefix. If `publication=true` and `publicationid` is not specified then the publications for this document (that the current member can access) are ordered alphabetically by display title (then by ID) and the first publication is used. ### ### URL There are three ways to invoke this service depending on document identifier: | Identifier | URL pattern | Example | | --- | --- | --- | | [URI ID](../../reference/glossary/uri_id.md) | `/ps/uri/{uriid}{ext?}` | `/ps/uri/123` or `/ps/uri/123.gif` | | [DocID](../../reference/glossary/document_id_docid.md) | `/ps/docid/{docid}` | `/ps/docid/myid123` | | Path | `/ps/uri?path={path}` | `/ps/uri?path=/ps/sample/demo/doc.psml` | The extension `{ext}` is optional and only used for clients who might need to infer the media type from the file extension. PageSeeder always returns the media type in the response headers. ### HTTP caching The HTTP cache headers returned depend on the publication (if any) and whether there is any content transcluded from other documents as follows: | | no publication | publication root accessible to `ps-group` | publication root NOT accessible to `ps-group` | | --- | --- | --- | --- | | transcluded content | `Cache-Control: no-cache` | `Cache-Control: no-cache` | `Cache-Control: no-cache` | | NO transcluded content | `Cache-Control: must-revalidate` `ETag: [document etag]` `Last-Modified: [document modified date]` | `Cache-Control: must-revalidate` `ETag: [publication etag]` `Last-Modified: [publication modified date]` | `Cache-Control: private, must-revalidate` `ETag: [publication etag]` `Last-Modified: [publication modified date]` | ### Comparisons You can also use this service to return the result of a comparison between: - two [versions](../../reference/glossary/version.md) of a document (with `version` and `compare` parameters) - two [document events](../../reference/glossary/document_event.md) occurring on a document (with `versionid` and `compareid` parameters) - a document and another document You can compare PSML documents. > **Tip:** You can also compare the metadata of non-PSML documents if you set the `psml` parameter to `true` , otherwise the comparison parameters are ignored. If the value is a float or ISO 8601 date (i.e. `yyyy-mm-dd`) and none match, the closest previous version is loaded. The table below summarizes the parameter used to select the state of the document to compare. | Main document | Compare document | Description | | --- | --- | --- | | `version` | `compare` | Document version, or `current` or `original`  | | `versionid` | `compareid` | Document event ID | | `position` | `compare-position` | Position within publication | | `publicationid` | `compare-publicationid` | Publication ID | > **Note:** You can compare a version of a document with its state by event ID (i.e. you can use `version` with `compareid` or `versionid` with `compare`. ## Parameters | Name | Description | Required | Type | Default value | | --- | --- | --- | --- | --- | | behavior | If set to `download`, add filename attachment headers to trigger download by browser | no | string | | | compareuriid | The URI ID of the document to compare with. | no | long | \[uriid\] | | compareid | The version ID to compare the selected version with (overrides `compare`) As of PageSeeder v5.99 it can be any [event](../elements/element_event.md) ID. | no | long | | | compare | The version to compare the selected version with (applies to auto-numbering). If `original` or `current`, compare with original or current version. If the value is a float or ISO 8601 date and none match, the closest previous version is loaded. | no | string | | | compare-diffx | The diffx markup to include for comparison, can be `none`, `combined`, `split`  (`true=combined` and if no `compareid` or `compare`, compare with current version) | no | enum | `none` | | compare-position | The position (instance number) of the compare document in the publication (requires `publication=true` and `compareuriid` ) | no | integer | `[first embedded position of URI]` | | compare-publicationid | The ID of the publication for compare document numbering (requires `publication=true` and `compareuriid`) | no | publicationid | `[first publication found for URI]` | | fragment | The fragment ID of the PSML to return | no | fragmentid | | | group | The group for the document edits (for backward compatibility, pre v6 different groups could have different edits) | no | string | \[the first user’s group with access\] | | ps-reload | Whether to refresh the document XML cache contents (requires `psml=true` for non-PSML documents) | no | boolean | `false` | | psml | Whether to return PSML metadata for non-PSML files | no | boolean | `false` | | position | The position (instance number) of this document in the publication (requires `publication=true`) | no | integer | `[first embedded position of URI]` | | publication | Whether to use publication for version and adjustments (e.g. numbering) in content | no | boolean | `false` | | publicationid | The ID of the publication context for version and numbering, empty means standalone (requires `publication=true`) | no | publicationid | `[first publication found for URI]` | | transclude | Whether to transclude content for transclude xrefs (only applies if no `compare*` parameters) | no | boolean | `false` | | versionid | The version ID of the document/metadata to return (overrides `version`). As of PageSeeder v5.99 it can be any [event](../elements/element_event.md) ID. | no | long | | | version | The version of the document/metadata to return (applies to transclusions and auto-numbering). If ‘original’ or ‘current’, load original or current version. If the value is a float or ISO 8601 date and none match, the closest previous version is loaded. | no | string | `current` | > **Note:** For backward compatibility parameter names can be prefixed by “ps-” and “docPath” can be used for "path". ### behavior This parameter affects the value of the `Content-Disposition` HTTP response header which indicates if the content is expected to be displayed *inline* in the browser or as an *attachment* that is downloaded and saved locally. The `filename` directive is always included. If this parameter is set to `download`, the `Content-Disposition` set to `attachment` to trigger a download. For example: `Content-Disposition=attachment; filename="sample.psml"` Otherwise, the response includes the `Content-Disposition` set to `inline`. For example: `Content-Disposition=inline; filename="sample.psml"` ### compare This parameter specifies which [version](../../reference/glossary/version.md) to compare with the selected version. It is the equivalent of the `version` parameter for the comparison document. ### compareid The ID of a [document history event](../../reference/glossary/document_event.md) to compare the selected document with, it is the equivalent of the `versionid` parameter for the comparison document. When specified, this parameter overrides the `compare` parameter. > **Note:** Before PageSeeder v5.99, this parameter could only be used for versions. ### compareuriid This parameter lets you specify a URI ID to compare the document with another document (requires `compare` or `compareid`). > **Tip:** This is mostly useful when comparing [document variations](../../reference/glossary/variation.md). ### compare-diffx This parameter selects the type of markup returned by the comparison algorithm. If no `compareid` or `compare` parameter is specified in the request, it compares with current version. When set to `none`, only the markup of the selected document is returned as if no comparison occurred but it still includes [\](../../psml/elements/element-compareto.md) and [\](../../psml/elements/element-compare.md) elements. #### Combined When set to `combined`, the comparison markup includes both insertions (``) and deletions (``) in the same document, which lets the user see the changes as a single view. > **Note:** For backward-compatibility, this service also support `true` instead of `combined`. In the combined view, the [\ element](../../psml/elements/element-diff.md) contains all the changes, as in the following example: ```xml ... Simple document Simple Sample document
Sample document
...
``` > **Tip:** The combined view is more compact and very effective when there are simple text changes, however, since it generates a document mixing both inserted and deleted content, it is more difficult to read and understand the changes when there are many complex changes. #### Split When set to `split`, the comparison markup returns the selected document with insertions (``) and the compared document with deletions (``). The split view lets use compare document side-by-side and which each side showing the version of the document they correspond to. In the split view, the [\ element](../../psml/elements/element-diff.md) only shows deletions, and insertions are shown inline in the regular content. ```xml ... Simple document Simple document
Sample document
...
``` ### compare-position This parameter lets you specify the position of the compare document in the publication. This is useful in case a document is referenced multiple times within a single publication as it affects the numbering. The `position` parameter requires both `publication=true` and `compareuriid` and is ignored otherwise. If it is not specified, this services assumes that the first instance of the document in the publication. ### compare-publicationid The ID of the publication for the compare document. This parameter lets you compare the selected document with another document from a different publication. It requires `publication=true` and `compareuriid`. ### fragment The fragment ID of the PSML to return. If specified only the corresponding [\](../elements/element_document-fragment.md) element is returned and it can be used to compare the same fragment in different documents. It only applies to PSML documents or when the `psml=true` parameter is specified. *Requires PageSeeder v6.0008 or higher.* ### group The group for the document edits. For backward compatibility, pre v6 different groups could have different edits) If you specify a group, PageSeeder also checks that you have permission to use that group. ### position This parameter lets you specify the position of this document in the publication. This is useful in case a document is referenced multiple times within a single publication as it affects the numbering. The `position` parameter requires `publication=true` as it has no effect outside the context of a publication. If it is not specified, this services assumes that the first instance of the document in the publication. ### publication A Boolean parameter to indicate whether to use the publication version or document version. When set to `true`, the service returns the publication version and adjusts the numbering for the publication. It also computes the last modified date based on the Table of Contents (TOC) of the publication which affects the caching response. When set to `false`, the service returns the document version and adjusts the numbering as if the document was standalone. The last modified date is the URI’s last modified date. ### publicationid The ID of the publication context for version and numbering. This parameter is ignored unless `publication=true`. If this parameter is empty, the service returns the document version instead and does not compute the numbering. ### ps-reload Use `ps-reload=true` to force PageSeeder to refresh the PSML document cache for this document only. This parameter has no effect on non-PSML documents, unless `psml=true` is also specified. ### psml This Boolean parameter indicates whether this service returns the raw content or the corresponding PSML metadata document. This parameter has no effect for PSML documents. For example, when requesting and image with `/ps/uri/123.png`, this service returns the image file. When setting the `psml` to `true`, the service returns the following instead: ```xml overview.png ``` ### transclude This Boolean parameter indicates whether the content for xrefs of type `transclude` should be included inline with the content. If set to `false` the xref in the returned PSML contains the display text or is empty, for example: ```xml Info ``` If set to `true`, PageSeeder pulls the transcluded content and injects it inside the xref in the returned PSML, as in the following example: ```xml This content has been transcluded ``` The `transclude` parameter has no effect if the returned content is not PSML or during comparisons as it only applies if no `compare*` parameters. > **Note:** The transcluded content is only returned if the user has permission to access that content. This is only significant when the source document and target document are in different groups. ### version The `version` parameter selects the version of the PSML document or PSML metadata document to return. > **Note:** When comparing versions, the auto-numbering is applied and compared. The value of the `compare` parameter can be: - `original` – a special keyword referring to the original state of the document when it was created or uploaded - `current` – a special keyword referring to the current state of the document - The name of an existing document version When the specified version does not exist: - If the value is an ISO 8601 date (i.e. `yyyy-mm-dd`), the closest previous date is loaded. **Example: **if versions `2020-10-11` an `2022-01-03` exist and the parameter is `2022-01-01` , the version selected for comparison is `2020-10-11`. - If the value is a floating number, each part if evaluated separately to match the closest lower integer version is loaded **Example 1**: if versions `0.5` an `0.8` exist and the parameter is `0.7` , the version selected for comparison is `0.5`. **Example 2**: if versions `1.1` an `1.2` exist and the parameter is `1.11` , the version selected for comparison is `1.2`. **Example 3**: if versions `1.10` an `1.20` exist and the parameter is `1.11` , the version selected for comparison is `1.10`. - Otherwise, the original version is returned. ### versionid This parameter if the lets you retrieve the state of the document at the time of a specific [document history event](../../reference/glossary/document_event.md), including: - Version – for version name or number, use the `compare` parameter instead - Workflow events, for example when the document changes status or is assigned - Individual edits - Notes added to edits - Comment mades to a fragment or the document If the specified version id is `0`, the original version is returned. When specified, this parameter overrides the `version`  parameter. > **Note:** Before PageSeeder v5.99, this parameter could only be used for versions. ## Permission You must have permission to view the document in order to invoke this service. If you specify a group parameter, you must also have permission got access this group. > **Note:** This service only considers permissions to the document for access control. If the document includes transclusions from groups that the users does not have permission to view, the transcluded content is not returned. ## Response The response depends mainly on: - The [media type](../../reference/glossary/media_type.md) of the document - Whether the `psml` parameter is used The parameters used for comparison and for publications affect the PSML being returned only. If the content includes transclusion, the permissions of the user might affect their content. ## PSML document example When requesting a PSML document, for example `/ps/uri/1234.psml`, this service always returns the source PSML. | HTTP Header | Value | | --- | --- | | `Content-Type` | `application/vnd.pageseeder.psml+xml ` | | `Content-disposition`  | `inline; filename=simple_document.psml` | ```xml Simple document
Simple document
``` ## Image example When using this service to retrieve non-PSML, it returns the actual content of the file with the  HTTP header to its native media type, for example: | HTTP Header | Value | | --- | --- | | `Content-Type` | `image/png` | | `Content-disposition`  | `inline; filename=overview.png` | If `psml=true`, this service returns the PSML metadata: | HTTP Header | Value | | --- | --- | | `Content-Type` | `application/vnd.pageseeder.psml+xml ` | | `Content-disposition`  | `inline; filename=overview.png.psml` | ```xml overview.png ``` ## URL example When using this service to retrieve URLs, it returns the URL as an internet shortcut with the `Content-Type` HTTP header set to `text/url`, for example: | HTTP Header | Value | | --- | --- | | `Content-Type` | `text/url` | | `Content-disposition`  | `inline; filename=psml.url` | ```text [InternetShortcut] https://dev.pageseeder.com/psml.html ``` > **Warning:** PageSeeder’s response might change in the future when downloading a raw URL file, if your API needs to download URLs, use the PSML version with `psml=true`. If `psml=true`, this service returns the PSML metadata: | HTTP Header | Value | | --- | --- | | `Content-Type` | `application/vnd.pageseeder.psml+xml ` | | `Content-disposition`  | `inline; filename=psml.html.psml` | ```xml PSML A complete reference of PageSeeder's markup language PSML ``` ## Folder example When using this service to retrieve folder, it returns a 204 (no content) response. If `psml=true`, this service returns the PSML metadata: | HTTP Header | Value | | --- | --- | | `Content-Type` | `application/vnd.pageseeder.psml+xml ` | | `Content-disposition`  | `inline; filename=demo.psml` | ```xml Demo ``` ## Error handling | HTTP Code | Error condition | | --- | --- | | 400 | Parameter `versionid` or `compareid` is not a valid number (long) | | 404 | No document matching URI ID, DocID or Path | | 404 | The compare URI ID could not be found |