---
title: "Validate a Source definition"
method: POST
path: "/v25-10-beta/agentic-logic/sources/validate"
tags: ["Agentic Logic"]
---

# Validate a Source definition

`POST /v25-10-beta/agentic-logic/sources/validate`

## Request

- Base URL: `https://api.intelligems.io`
- URL: `https://api.intelligems.io/v25-10-beta/agentic-logic/sources/validate`
- 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/validate/post.ts> (a function with typed inputs; its response is checked against the schema)

```http
POST /v25-10-beta/agentic-logic/sources/validate
```

Runs the checks a `PUT` of the definition would run, without storing anything.

- `definition` (object, required) — A Source definition, the same shape as the
  `PUT` body's `definition`.
- The response is `{ "valid": true, "warnings": [...] }` or
  `{ "valid": false, "errors": [...], "warnings": [...] }`. `errors` are why a
  `PUT` would answer 400; `warnings` never block a write.
- Script Sources are checked for the `build` export, ESM compatibility, the
  sandbox source guard, and a compilable `outputSchema`; GraphQL Sources for
  an input-independent document. Other kinds have no write-time checks.
- A failed check is a `200` with `valid: false`; a malformed body is a 400.

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.

## Request body

- object
  - `definition` union, required: The SDK read a Source names, restricted to reads whose answer does not depend on the request: best sellers, new arrivals, in stock, one collection page, a stored GraphQL query (storefrontGraphql: `$country: CountryCode!` + `@inContext(country: $country)`, country never stored; adminGraphql: catalog/content root fields only, no customer, order or cost fields), or a script (one `source.ts` exporting `async function build(sdk)` that the platform runs on a schedule in a sandbox; its JSON return value, up to 1 MiB, is the Source's answer, read with sdk.getSourceRaw). A GraphQL Source stores ALL of its variables. A typed or GraphQL Source's answer shares the read-cache entry of the equivalent direct SDK read; a script's value has its own entry.
    - 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

## Response `200`

OK

- union
  - object
    - `valid` true, required
    - `warnings` string[], required
  - object
    - `valid` false, required
    - `errors` string[], required
    - `warnings` string[], required

## Other responses

- `429`: Too Many Requests

## Changes

- **2026-11-06** `7b769b2f90b1`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/intelligems/apis/intelligems-external-api-v25-10-beta/changes/v25-10-beta/agentic-logic/sources/validate/post.md)

---

[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)