@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.13

package/agent-docs/content-delivery/http-api/operations/list-content-resources-8e977ec7.md

@@ -0,0 +1,913 @@
+---
+id: reference.content-rest.listContentResources
+title: List resource metadata
+summary: GET /resources
+type: api-reference
+area: api
+subarea: api-reference
+canonical: /content-delivery/http-api/operations/list-content-resources-8e977ec7
+---
+
+# List resource metadata
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Reference](https://www.shoalrun.com/.well-known/shoalrun/navigation/reference-tab-50f26fe22670.txt) (ID: reference-tab). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Reference](https://www.shoalrun.com/cli.md) > Content delivery > Content REST API > Other > List resource metadata
+
+**Updated: 2026-09-27.**
+
+This reference is generated from the OpenAPI description. It shows the operation contract; follow any related guides below for task steps and context.
+
+OpenAPI for this operation: [Download JSON](https://www.shoalrun.com/api/operations/production/current/en/content-rest-listcontentresources-b664cb30bd0fc4c2a4b13ada9e7591355af7d9f084fa9def4c21b785fece1861.json).
+
+## GET /resources
+
+List resource metadata
+
+Query parameters are single-valued; unknown or duplicate parameters are rejected. Publication and revision checks run before conditional ETag checks. No pagination, search, writes, authentication, or cross-origin policy is supplied by this reference adapter.
+
+### Servers
+
+`/content/v1`
+
+### Parameters
+
+#### channel (query)
+
+Required
+
+Exact publication channel. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"production"`
+
+#### version (query)
+
+Required
+
+Exact publication version. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"current"`
+
+#### language (query)
+
+Required
+
+Exact publication language. No default or fallback.
+
+string; minLength: 1; maxLength: 2048
+
+**Default example**: `"en"`
+
+#### revision (query)
+
+Optional
+
+Omit to discover the currently supplied snapshot. Supply to require that exact revision.
+
+string; pattern: ^\[a-f0-9]{64}$
+
+**Default example**: `"0770e6d70db51967fac8dcc7bb4ff5a5bff87378eb2e2bbb63dea93d090c82e8"`
+
+#### If-None-Match (header)
+
+Optional
+
+An ETag, comma-separated ETags, or \*. Weak comparison is supported for GET and HEAD.
+
+string
+
+### Example request
+
+```bash
+curl --request GET \
+  --url 'https://YOUR_API_HOST/content/v1/resources?channel=YOUR_CHANNEL&version=YOUR_VERSION&language=YOUR_LANGUAGE'
+```
+
+### Responses
+
+#### 200: OK
+
+`application/json`
+
+The selected resource or inventory.
+
+##### Response headers
+
+###### ETag
+
+Optional
+
+Strong SHA-256 validator of the exact UTF-8 response bytes.
+
+Serialization: simple; explode: false.
+
+string
+
+###### Cache-Control
+
+Optional
+
+Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.
+
+Serialization: simple; explode: false.
+
+string
+
+4 properties
+
+- `schemaVersion` `number` **always present** 
+
+  const: 1
+
+- `revision` `string` **always present** 
+
+  pattern: ^\[a-f0-9]{64}$
+
+- `publication` `object` **always present** 
+
+  3 properties
+
+  - `channel` `string` **always present** 
+
+    minLength: 1
+
+  - `version` `string` **always present** 
+
+    minLength: 1
+
+  - `language` `string` **always present** 
+
+    minLength: 1
+
+  Additional properties: not allowed.
+
+- `resources` `list of object` **always present** 
+
+  Array items:
+
+  2 properties
+
+  - `key` `string` **always present** 
+
+    Opaque stable typed-reference key. Use the returned key. It is k\_ followed by unpadded base64url of UTF-8 JSON for \["page",documentId], \["section",documentId,sectionId], or \["snippet",id]. Publication and revision are separate selectors.
+
+    pattern: ^k\_\[A-Za-z0-9\_-]+$
+
+  - `resource` `object` **always present** 
+
+    10 properties
+
+    - `publication` `object` **always present** 
+
+      3 properties
+
+      - `channel` `string` **always present** 
+
+        minLength: 1
+
+      - `version` `string` **always present** 
+
+        minLength: 1
+
+      - `language` `string` **always present** 
+
+        minLength: 1
+
+      Additional properties: not allowed.
+
+    - `title` `string` **always present** 
+
+    - `summary` `string` **always present** 
+
+    - `type` `string` **always present** 
+
+    - `canonicalUrl` `string` **may be absent** 
+
+      format: uri
+
+    - `representations` `object` **always present** 
+
+      minProperties: 1
+
+      2 properties
+
+      - `html` `object` **may be absent** 
+
+        6 properties
+
+        - `path` `string` **always present** 
+
+          pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+        - `bytes` `integer` **always present** 
+
+          minimum: 0
+
+        - `digest` `string` **always present** 
+
+          pattern: ^\[a-f0-9]{64}$
+
+        - `mediaType` `string` **always present** 
+
+        - `anchors` `list of object` **always present** 
+
+          Array items:
+
+          object
+
+          3 properties
+
+          - `id` `string` **always present** 
+
+          - `exportedId` `string` **always present** 
+
+          - `title` `string` **may be absent** 
+
+          Additional properties: not allowed.
+
+        - `links` `list of one of several types` **always present** 
+
+          Array items:
+
+          The response has exactly one of these shapes:
+
+          **Shape 1** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present** 
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"resource"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `ref` `one of several types` **always present**&#x20;
+
+            The response has exactly one of these shapes:
+
+            **Shape 1** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "page"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            Additional properties: not allowed.
+
+            **Shape 2** · 3 properties
+
+            object
+
+            3 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "section"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            - `sectionId` `string` **always present**&#x20;
+
+              pattern: ^\[a-z0-9]\[a-z0-9-]{0,511}$
+
+            Additional properties: not allowed.
+
+            **Shape 3** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "snippet"
+
+            - `id` `string` **always present**&#x20;
+
+              pattern: ^\[A-Za-z\_]\[A-Za-z0-9\_.-]\*$
+
+            Additional properties: not allowed.
+
+          Additional properties: not allowed.
+
+          **Shape 2** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"asset"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `asset` `string` **always present**&#x20;
+
+            pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+          Additional properties: not allowed.
+
+          **Shape 3** · 5 properties
+
+          object
+
+          5 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"canonical"`, `"external"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          Additional properties: not allowed.
+
+        Additional properties: not allowed.
+
+      - `markdown` `object` **may be absent**&#x20;
+
+        6 properties
+
+        - `path` `string` **always present**&#x20;
+
+          pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+        - `bytes` `integer` **always present**&#x20;
+
+          minimum: 0
+
+        - `digest` `string` **always present**&#x20;
+
+          pattern: ^\[a-f0-9]{64}$
+
+        - `mediaType` `string` **always present**&#x20;
+
+        - `anchors` `list of object` **always present**&#x20;
+
+          Array items:
+
+          object
+
+          3 properties
+
+          - `id` `string` **always present**&#x20;
+
+          - `exportedId` `string` **always present**&#x20;
+
+          - `title` `string` **may be absent**&#x20;
+
+          Additional properties: not allowed.
+
+        - `links` `list of one of several types` **always present**&#x20;
+
+          Array items:
+
+          The response has exactly one of these shapes:
+
+          **Shape 1** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"resource"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `ref` `one of several types` **always present**&#x20;
+
+            The response has exactly one of these shapes:
+
+            **Shape 1** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "page"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            Additional properties: not allowed.
+
+            **Shape 2** · 3 properties
+
+            object
+
+            3 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "section"
+
+            - `documentId` `string` **always present**&#x20;
+
+              minLength: 1
+
+            - `sectionId` `string` **always present**&#x20;
+
+              pattern: ^\[a-z0-9]\[a-z0-9-]{0,511}$
+
+            Additional properties: not allowed.
+
+            **Shape 3** · 2 properties
+
+            object
+
+            2 properties
+
+            - `kind` `string` **always present**&#x20;
+
+              const: "snippet"
+
+            - `id` `string` **always present**&#x20;
+
+              pattern: ^\[A-Za-z\_]\[A-Za-z0-9\_.-]\*$
+
+            Additional properties: not allowed.
+
+          Additional properties: not allowed.
+
+          **Shape 2** · 6 properties
+
+          object
+
+          6 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"asset"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          - `asset` `string` **always present**&#x20;
+
+            pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+          Additional properties: not allowed.
+
+          **Shape 3** · 5 properties
+
+          object
+
+          5 properties
+
+          - `key` `string` **always present**&#x20;
+
+          - `kind` `enum<string>` **always present**&#x20;
+
+            Available options: `"canonical"`, `"external"`
+
+          - `href` `string` **always present**&#x20;
+
+          - `fragment` `string` **may be absent**&#x20;
+
+          - `query` `string` **may be absent**&#x20;
+
+          Additional properties: not allowed.
+
+        Additional properties: not allowed.
+
+      Additional properties: not allowed.
+
+    - `assets` `list of string` **always present**&#x20;
+
+      uniqueItems: true
+
+      Array items:
+
+      string; pattern: ^(?:NOTICES\\.txt|(?:content|assets)/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+(?:/(?!\\.{1,2}(?:/|$))\[A-Za-z0-9\_.-]+)\*)$
+
+    - `externalDependencies` `list of object` **always present**&#x20;
+
+      Array items:
+
+      object
+
+      2 properties
+
+      - `url` `string` **always present**&#x20;
+
+        format: uri
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "image"
+
+      Additional properties: not allowed.
+
+    - `ref` `one of several types` **always present**&#x20;
+
+      The response has exactly one of these shapes:
+
+      **Shape 1** · 2 properties
+
+      object
+
+      2 properties
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "page"
+
+      - `documentId` `string` **always present**&#x20;
+
+        minLength: 1
+
+      Additional properties: not allowed.
+
+      **Shape 2** · 3 properties
+
+      object
+
+      3 properties
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "section"
+
+      - `documentId` `string` **always present**&#x20;
+
+        minLength: 1
+
+      - `sectionId` `string` **always present**&#x20;
+
+        pattern: ^\[a-z0-9]\[a-z0-9-]{0,511}$
+
+      Additional properties: not allowed.
+
+      **Shape 3** · 2 properties
+
+      object
+
+      2 properties
+
+      - `kind` `string` **always present**&#x20;
+
+        const: "snippet"
+
+      - `id` `string` **always present**&#x20;
+
+        pattern: ^\[A-Za-z\_]\[A-Za-z0-9\_.-]\*$
+
+      Additional properties: not allowed.
+
+    - `source` `object` **may be absent**&#x20;
+
+      minProperties: 1
+
+      3 properties
+
+      - `documentId` `string` **may be absent**&#x20;
+
+        minLength: 1
+
+      - `snippetId` `string` **may be absent**&#x20;
+
+        minLength: 1
+
+      - `valuesDigest` `string` **may be absent**&#x20;
+
+        pattern: ^\[a-f0-9]{64}$
+
+      Additional properties: not allowed.
+
+    Additional properties: not allowed.
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+##### Example: Illustrative content; discover keys and revision from your own host.
+
+Key: illustrative. Location: response 200; application/json. Authored in OpenAPI.
+
+```json
+{
+  "schemaVersion": 1,
+  "revision": "0770e6d70db51967fac8dcc7bb4ff5a5bff87378eb2e2bbb63dea93d090c82e8",
+  "publication": {
+    "channel": "production",
+    "version": "current",
+    "language": "en"
+  },
+  "resources": [
+    {
+      "key": "k_WyJwYWdlIiwiZ3VpZGUuYmlsbGluZyJd",
+      "resource": {
+        "ref": {
+          "kind": "page",
+          "documentId": "guide.billing"
+        },
+        "publication": {
+          "channel": "production",
+          "version": "current",
+          "language": "en"
+        },
+        "title": "Billing",
+        "summary": "Contact billing support.",
+        "type": "guide",
+        "representations": {
+          "html": {
+            "path": "content/resource-example.html",
+            "mediaType": "text/html",
+            "bytes": 24,
+            "digest": "0a97b73701c659be016f97a7be571c14c1cdad440cf79dfc1c8a0238a8b4787f",
+            "anchors": [],
+            "links": []
+          },
+          "markdown": {
+            "path": "content/resource-example.md",
+            "mediaType": "text/markdown",
+            "bytes": 17,
+            "digest": "d37729e92d86a1133926632326a5d61a3e65610a169d65211726924af02dac5c",
+            "anchors": [],
+            "links": []
+          }
+        },
+        "assets": [],
+        "externalDependencies": []
+      }
+    }
+  ]
+}
+```
+
+#### 304: Not Modified
+
+The validated selected response matches If-None-Match. No response body.
+
+##### Response headers
+
+###### ETag
+
+Optional
+
+Strong SHA-256 validator of the exact UTF-8 response bytes.
+
+Serialization: simple; explode: false.
+
+string
+
+###### Cache-Control
+
+Optional
+
+Unpinned discovery uses no-cache. Revision-pinned success uses public, max-age=31536000, immutable. Errors use no-store.
+
+Serialization: simple; explode: false.
+
+string
+
+#### 400: Bad Request
+
+`application/json`
+
+invalid_request: missing, duplicate, unknown, or malformed query parameter.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 404: Not Found
+
+`application/json`
+
+not_found: unknown publication, resource, or route.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 405: Method Not Allowed
+
+`application/json`
+
+method_not_allowed: only GET and HEAD are supported; Allow lists both.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+###### Allow
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "GET, HEAD"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 406: Not Acceptable
+
+`application/json`
+
+unsupported_format: unsupported or unavailable representation format.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 409: Conflict
+
+`application/json`
+
+stale_revision: revision unavailable, or source bytes no longer match the pinned snapshot.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.
+
+#### 500: Internal Server Error
+
+`application/json`
+
+internal_error: the source could not complete the request.
+
+##### Response headers
+
+###### Cache-Control
+
+Optional
+
+Serialization: simple; explode: false.
+
+const: "no-store"
+
+1 property
+
+- `error` `object` **always present**&#x20;
+
+  2 properties
+
+  - `code` `enum<string>` **always present**&#x20;
+
+    Available options: `"invalid_request"`, `"not_found"`, `"unsupported_format"`, `"stale_revision"`, `"method_not_allowed"`, `"internal_error"`
+
+  - `message` `string` **always present**&#x20;
+
+  Additional properties: not allowed.
+
+Additional properties: not allowed.