Shoalrun documentation frameworkMenu
For agents
Start with https://www.shoalrun.com/llms.txt for the documentation index, then read the Markdown pages it links. Skip to article. Documentation index. Read this page as Markdown.
API reference

List resource metadata

Updated
GET/resourcesView examples
Read as Markdown

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.

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

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.

          Additional properties: not allowed.

        • markdown 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.

          Additional properties: not allowed.

        Additional properties: not allowed.

      • assets list of string always present ⓘ

        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 ⓘ

        Array items:

        object

        2 properties

        • url string always present ⓘ

          format: uri

        • kind string always present ⓘ

          const: "image"

        Additional properties: not allowed.

      • ref one of several types always present ⓘ

        The response has exactly one of these shapes:

        Shape 1 · 2 properties

        object

        2 properties

        • kind string always present ⓘ

          const: "page"

        • documentId string always present ⓘ

          minLength: 1

        Additional properties: not allowed.

        Shape 2 · 3 properties

        object

        3 properties

        • kind string always present ⓘ

          const: "section"

        • documentId string always present ⓘ

          minLength: 1

        • sectionId string always present ⓘ

          pattern: ^[a-z0-9][a-z0-9-]{0,511}$

        Additional properties: not allowed.

        Shape 3 · 2 properties

        object

        2 properties

        • kind string always present ⓘ

          const: "snippet"

        • id string always present ⓘ

          pattern: ^[A-Za-z_][A-Za-z0-9_.-]*$

        Additional properties: not allowed.

      • source object may be absent ⓘ

        minProperties: 1

        3 properties

        • documentId string may be absent ⓘ

          minLength: 1

        • snippetId string may be absent ⓘ

          minLength: 1

        • valuesDigest string may be absent ⓘ

          pattern: ^[a-f0-9]{64}$

        Additional properties: not allowed.

      Additional properties: not allowed.

    Additional properties: not allowed.

Additional properties: not allowed.

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 ⓘ

    2 properties

    • code enum<string> always present ⓘ

      Available options: "invalid_request", "not_found", "unsupported_format", "stale_revision", "method_not_allowed", "internal_error"

    • message string always present ⓘ

    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 ⓘ

    2 properties

    • code enum<string> always present ⓘ

      Available options: "invalid_request", "not_found", "unsupported_format", "stale_revision", "method_not_allowed", "internal_error"

    • message string always present ⓘ

    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 ⓘ

    2 properties

    • code enum<string> always present ⓘ

      Available options: "invalid_request", "not_found", "unsupported_format", "stale_revision", "method_not_allowed", "internal_error"

    • message string always present ⓘ

    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 ⓘ

    2 properties

    • code enum<string> always present ⓘ

      Available options: "invalid_request", "not_found", "unsupported_format", "stale_revision", "method_not_allowed", "internal_error"

    • message string always present ⓘ

    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 ⓘ

    2 properties

    • code enum<string> always present ⓘ

      Available options: "invalid_request", "not_found", "unsupported_format", "stale_revision", "method_not_allowed", "internal_error"

    • message string always present ⓘ

    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 ⓘ

    2 properties

    • code enum<string> always present ⓘ

      Available options: "invalid_request", "not_found", "unsupported_format", "stale_revision", "method_not_allowed", "internal_error"

    • message string always present ⓘ

    Additional properties: not allowed.

Additional properties: not allowed.