---
title: "Create or replace a Source"
method: PUT
path: "/v25-10-beta/agentic-logic/sources/{name}"
tags: ["Agentic Logic"]
---

# Create or replace a Source

`PUT /v25-10-beta/agentic-logic/sources/{name}`

## Request

- Base URL: `https://api.intelligems.io`
- URL: `https://api.intelligems.io/v25-10-beta/agentic-logic/sources/{name}`
- Auth: API key in header `intelligems-access-token`
- TypeScript: <https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/docs/v25-10-beta/agentic-logic/sources/:name/put.ts> (a function with typed inputs; its response is checked against the schema)

```http
PUT /v25-10-beta/agentic-logic/sources/{name}
```

Creates the Source or replaces it in place, and takes effect immediately.

- `description` (string, required) — What the Source reads, for authors.
- `definition` (object, required) — What the Source reads.
- `freshMsOverride` (number, optional) — Freshness override, within the read
  kind's allowed range. Omit to use the kind's default.

A new Source, or one whose definition or freshness changed, gets an immediate
first refresh after the write commits. The response carries `warnings` the
author should reconsider.

Use the `intelligems-access-token` header. The token selects the organization; do not send `orgId`. The organization must have Agentic Logic enabled.

**Rate Limit:** 50 requests per 30s window, refilling 25 tokens every 30s.

## Path parameters

- `name` string, required

## Request body

- object
  - `description` string, required: What the Source reads and what rules use it for — the text an agent reads to judge reuse.
  - `definition` union, required: The typed read the Source names.
    - object
      - `kind` 'bestSellers', required
      - `args` object, required
        - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
        - `metric` 'units' | 'revenue': 'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.
        - `scope` object: Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.
          - `collectionIds` string[]: Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.
          - `tags` string[]: Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.
        - `limit` integer, required: Products to return, in rank order (max 250).
        - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.
    - object
      - `kind` 'newArrivals', required
      - `args` object, required
        - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
        - `dateField` 'created' | 'published': 'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.
        - `scope` object: Collections and/or tags to restrict the read to.
          - `collectionIds` string[]: Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.
          - `tags` string[]: Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.
        - `limit` integer, required: Products to return, newest first (max 250).
        - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.
    - object
      - `kind` 'inStock', required
      - `args` object, required
        - `minQuantity` integer: Minimum total inventory quantity, inclusive (default 1).
        - `scope` object: Collections and/or tags to restrict the read to.
          - `collectionIds` string[]: Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.
          - `tags` string[]: Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.
        - `orderBy` object: Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.
          - `field` 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal', required: 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key.
          - `direction` 'asc' | 'desc': 'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.
        - `limit` integer, required: Products to return (max 250).
    - object
      - `kind` 'collectionProducts', required
      - `args` object, required
        - `orderBy` object: Server-side sort.
          - `field` 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance', required: 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key.
          - `direction` 'asc' | 'desc': 'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.
        - `limit` integer, required: Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan).
        - `include` object: Extra per-product data to fetch (explicit metafield refs).
          - `collectionIds` union: Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.
            - boolean
            - object
              - …
          - `metafields` object[]: Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.
            - `namespace` string, required: Metafield namespace (e.g. 'custom').
            - `key` string, required: Metafield key within the namespace.
        - `collectionId` string, required: Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids.
    - object
      - `kind` 'storefrontGraphql', required
      - `args` object, required
        - `gql` string, required
        - `variables` object, required
    - object
      - `kind` 'adminGraphql', required
      - `args` object, required
        - `gql` string, required
        - `variables` object, required
    - object
      - `kind` 'script', required
      - `args` object, required
        - `workspace` object, required
          - `entry` 'source.ts'
          - `files` object, required
        - `outputSchema` object
  - `freshMsOverride` integer

## Response `200`

OK

- object
  - `source` object, required: One Source: a named, org-scoped read definition whose answer the platform keeps cached and refreshed. Rules read it with sdk.getSource(name), or sdk.getSourceRaw(name) for a GraphQL or script Source.
    - `name` string, required: The Source's stable lower-kebab name — what rule code passes to sdk.getSource(name) (sdk.getSourceRaw(name) for a GraphQL Source). Never renamed once rules ship against it.
    - `description` string, required: What the Source reads and what rules use it for — the text an agent reads to judge reuse.
    - `definition` union, required: The typed read the Source names.
      - object
        - `kind` 'bestSellers', required
        - `args` object, required
          - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
          - `metric` 'units' | 'revenue': 'units' (default, net items sold) or 'revenue' (net sales) — what the ranking orders by.
          - `scope` object: Collections and/or tags to restrict the ranking to. Tag scope narrows the ranking itself; collection scope filters the ranked products, so a tight collection can return fewer than `limit`.
            - `collectionIds` string[]: Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.
            - `tags` string[]: Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.
          - `limit` integer, required: Products to return, in rank order (max 250).
          - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after ranking, so the list can shrink below `limit`.
      - object
        - `kind` 'newArrivals', required
        - `args` object, required
          - `timeWindow` '24h' | '7d' | '30d' | '90d': '24h' | '7d' | '30d' | '90d' trailing window (default '30d').
          - `dateField` 'created' | 'published': 'created' (default) uses the product's creation date; 'published' uses the date it went live on the Online Store.
          - `scope` object: Collections and/or tags to restrict the read to.
            - `collectionIds` string[]: Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.
            - `tags` string[]: Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.
          - `limit` integer, required: Products to return, newest first (max 250).
          - `excludeOutOfStock` boolean: Drop products with no variant available for sale. Applied after the read, so the list can shrink below `limit`.
      - object
        - `kind` 'inStock', required
        - `args` object, required
          - `minQuantity` integer: Minimum total inventory quantity, inclusive (default 1).
          - `scope` object: Collections and/or tags to restrict the read to.
            - `collectionIds` string[]: Collection GIDs (gid://shopify/Collection/…). A product matches if it is in any of them.
            - `tags` string[]: Product tags; a product matches if it carries any of them. Tag matching is exact after case-folding — Shopify tags are case-insensitive.
          - `orderBy` object: Sort. Default is highest inventory first ('inventoryTotal' desc); 'price' and 'bestSelling' only sort server-side inside exactly one collection.
            - `field` 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal', required: 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key.
            - `direction` 'asc' | 'desc': 'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.
          - `limit` integer, required: Products to return (max 250).
      - object
        - `kind` 'collectionProducts', required
        - `args` object, required
          - `orderBy` object: Server-side sort.
            - `field` 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance', required: 'bestSelling' | 'price' | 'createdAt' | 'title' | 'relevance' | 'inventoryTotal' — the sort key.
            - `direction` 'asc' | 'desc': 'asc' (default) or 'desc'. Compiles to the operation's `reverse` flag.
          - `limit` integer, required: Maximum products to return. Positive integer, max 250 per read; postFetch queries may scan more than they return (see scan).
          - `include` object: Extra per-product data to fetch (explicit metafield refs).
            - `collectionIds` union: Fetch Storefront-visible collection GIDs for each product. Use true for the first 20, or { first: N } to request 1–250. Use this for post-fetch collection scope checks.
              - …
            - `metafields` object[]: Metafields to fetch (explicit namespace/key each). Values come back on AgenticLogicProduct.metafields; a hidden or absent metafield yields a null value.
              - …
          - `collectionId` string, required: Scope the query to one collection (gid://shopify/Collection/<n>, or the bare numeric id the Shopify admin shows). Required for where.server.productFilters. Cannot be combined with ids.
      - object
        - `kind` 'storefrontGraphql', required
        - `args` object, required
          - `gql` string, required
          - `variables` object, required
      - object
        - `kind` 'adminGraphql', required
        - `args` object, required
          - `gql` string, required
          - `variables` object, required
      - object
        - `kind` 'script', required
        - `args` object, required
          - `workspace` object, required
            - `entry` 'source.ts', required
            - `files` object, required
          - `outputSchema` object
    - `summary` string, required: One human-readable line describing the read.
    - `freshMs` integer, required: How long a fetched answer counts as fresh, in ms: the override when set, else the read kind's default. The scheduled refresh runs at about 80% of it.
    - `freshMsOverride` integer, nullable, required: The Source's own freshness in ms, shorter or longer than the read kind's default (1 minute to 24 hours for a read; 15 minutes to 7 days for a script); null when the Source follows the default.
    - `status` 'warming' | 'ready' | 'stale' | 'error', required: warming (never fetched), ready (fresh), stale (older than freshMs, still served while it refreshes) or error (the last refresh failed).
    - `fetchedAt` number, nullable, required: When the cached answer was fetched, epoch ms; null when nothing is cached.
    - `lastRefreshedAt` number, nullable, required: When the last scheduled or requested refresh finished, epoch ms; null when none has run.
    - `lastRefreshStatus` 'ok' | 'error', nullable, required: Outcome of the last scheduled or requested refresh; null when none has run.
    - `lastError` string, nullable, required: Why the last refresh failed; null after a successful refresh.
    - `lastBuildLog` string, nullable, required: The console output of a script Source's last build (its tail, at most 8 KiB), whether it succeeded or failed; null for other kinds and before the first build.
    - `lastReadAt` number, nullable, required: When a rule last read the Source, epoch ms (recorded at most every 10 minutes); null when never read. Sources idle for 7 days stop refreshing.
    - `lastUpdateTs` number, required: When the Source definition was last written, epoch ms.
  - `warnings` string[], required

## Other responses

- `429`: Too Many Requests

---

[API](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta.md) - [All operations](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/llms.txt) - [OpenAPI document](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/revisions/7b769b2f90b1?raw)