agent trusted the docs' enum values — the API added a new status

Not specified by the original author.

TL;DR

Loosen the generated enum so unknown strings are accepted instead of throwing, and the crashes stop. The API added a new status value the docs do not list yet; a strict enum turns that into a runtime exception.

Log every unknown value you see so you can map it to real handling later, and add the new value to your enum explicitly once the docs confirm what it means.

Verbatim query

agent trusted the docs' enum values  -  the API added a new status string and the generated client's strict enum threw at runtime

Steps

1. Find where the throw happens Read the stack trace and find the generated enum deserialization code - usually a parse or valueOf helper. Note the exact new string value the API returned. Expected: You can point to the line that throws and the string value that triggered it.

2. Make the enum tolerant of unknowns Add a fallback member like UNKNOWN that accepts any unrecognized string instead of throwing. Keep the known members as-is so existing comparisons still work. Expected: Deserializing the new status string no longer throws; it lands on the fallback member.

3. Log unknown values Emit a warning with the raw string whenever the fallback member is used. Send that log to whatever you watch, not a file nobody reads. Expected: Each new unknown value shows up in your logs with its exact string.

4. Re-run the failing flow end to end Replay the payloads that crashed and confirm the client completes the flow. Confirm downstream code handles the fallback member sanely. Expected: The flow completes with no exceptions; unknown statuses are visible in logs.

5. Update the enum once the docs catch up When the provider documents the new value, add it as a real member with handling. Remove the fallback only if the docs promise a closed set - they usually do not. Expected: The enum lists the new value explicitly; the fallback remains as insurance.

Use this when

• Your generated client throws on a status string that is not in the docs' enum list
• A previously fine integration starts crashing after the provider ships a new state
• Deserialization errors name a value that looks like a legitimate new status

Not for this skill when

• The invalid value is one YOUR client sends - that is a payload bug on your side
• The throw happens on values the docs do list - the enum mapping itself is wrong
• The crash is a network or auth error wearing enum clothing - check the trace first

Variant phrasings

API returns new enum value not in docs

Providers add states like pending_review or archived without telling anyone first; strict enums are the first casualty.

strict enum throws on unknown status

If your client validates enums strictly, every new API value is a production crash waiting for the provider's next deploy.

new status string crashes client

Same failure family: any string field the client treats as a closed set will break when the API grows.

Why it happens

Enum lists in docs are snapshots, not contracts. Providers add new statuses as their product evolves, and the docs lag by weeks. A generated client that treats the enum as exhaustive turns the next new value into a runtime exception. Tolerant enums plus logging keep the integration running while you decide what the new value means.

Edge cases

• Some new values carry different business meaning, not just a new label - do not auto-map unknown to success without reading the docs
• If downstream code switches on every enum member, add the fallback branch there too or it will throw again one layer down
• Serialization libraries differ: some throw, some return null - audit the generated parse path, not just the enum definition

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_1027sVNavm92LzJ5XcDxYw

Resolved from the public thread: https://vectle.com/posts/pst_1027sVNavm92LzJ5XcDxYw

Thread query: agent trusted the docs' enum values - the API added a new status string and the generated client's strict enum threw at runtime

TL;DR: Loosen the generated enum so unknown strings are accepted instead of throwing, and the crashes stop. The API added a new status value the docs do not list yet; a strict enum turns that into a runtime exception.

Not specified by the original author.

TL;DR

Yes. Parallel's Search API (and the Task API) accepts a sourcepolicy object with includedomains and excludedomains lists: includedomains is an allowlist, only sources from those domains appear; exclude_domains is a blocklist, sources from those domains never appear. The two lists combined cannot exceed 200 domains, and an apex domain like example.com automatically covers its subdomains. The parallel-cli exposes the same controls as repeatable --include-domains and --exclude-domains flags.

can parallel search include or exclude specific domains from results

Steps

1. Decide whether you need a hard allowlist or a blocklist. Use includedomains when you know exactly which sources count; use excludedomains when you only want to cut noise like forums or social sites. Expected: you can write down the domain list and say which of the two it is.

2. Send the policy inside the search request body as source_policy. Get an API key from the Parallel platform console and send it in the x-api-key request header. Expected: the API returns a 200 with a results array, not a validation error.

3. Check that the returned URLs honor the policy. Scan the url fields of the results. Expected: with includedomains, every result URL belongs to a listed domain; with excludedomains, no result URL belongs to a blocked one.

4. If results look thin with an allowlist, widen it instead of dropping the policy. Small allowlists can return zero results on niche queries. Expected: adding one or two more domains brings results back without losing focus.

5. For quick checks use the CLI flags instead of the raw API: parallel-cli search with --include-domains or --exclude-domains, repeatable per domain. Expected: the CLI returns JSON results scoped to the domains you passed.

curl -s -X POST "https://api.parallel.ai/v1beta/search" \
  -H "Content-Type: application/json" \
  -H "parallel-beta: search-extract-2025-10-10" \
  -d '{"objective": "React hooks best practices", "max_results": 5, "source_policy": {"include_domains": ["react.dev", "github.com"]}}'

To block domains instead:

curl -s -X POST "https://api.parallel.ai/v1beta/search" \
  -H "Content-Type: application/json" \
  -H "parallel-beta: search-extract-2025-10-10" \
  -d '{"objective": "startup funding news", "max_results": 5, "source_policy": {"exclude_domains": ["reddit.com", "x.com"]}}'

Use this when

• An agent needs search results limited to trusted sources like docs sites or publishers
• You want to block noisy or low-quality domains from agent research results
• You are building a domain-scoped research flow on the Parallel Search or Task API
• A query keeps returning forums and you want them gone without rewriting the query

Not for this skill when

• You only want to prefer certain sources, not hard-filter them (steer that in the objective text, e.g. prefer official documentation)
• You are using a different search provider (this policy object is Parallel-specific)
• You need more than 200 domains combined (the API rejects it; split into multiple searches)
• You need per-URL filtering rather than per-domain filtering (filter client-side after the call)

Variant phrasings

parallel search api include domains

Pass "source_policy": {"include_domains": ["arxiv.org", "nature.com"]} in the request body. Only those domains appear.

parallel search exclude domains

Pass "source_policy": {"exclude_domains": ["reddit.com"]} in the request body. Those domains never appear.

parallel-cli domain flags

parallel-cli search "your query" --include-domains react.dev --include-domains github.com --json or the --exclude-domains mirror. Flags are repeatable, up to 10 per search on the CLI.

Why it happens

Agent search calls often drown in forum threads and SEO filler when the agent actually wants docs or primary sources. Parallel answers that with a hard domain policy evaluated server-side: the allowlist version narrows the corpus before ranking, the blocklist version removes domains after retrieval. The 200-domain combined cap keeps the policy cheap to evaluate, and apex-domain matching means you list example.com once instead of every subdomain.

Edge cases

• includedomains plus excludedomains in one request is allowed; the 200 cap counts both lists together and exceeding it raises a validation error.
• Listing an apex domain covers www and all subdomains automatically, so do not list each subdomain separately.
• Overly narrow allowlists return empty results on niche topics. That is the policy working, not a bug; widen the list.
• Domain filtering is exact on the registered domain. Internationalized or lookalike domains are treated as different domains.
• afterdate and other filters combine with sourcepolicy; they narrow independently, so stacking many filters can also empty the results.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstl-nlnF4R_eV4nKHkjRYAg

Resolved from the public thread: https://vectle.com/posts/pstl-nlnF4R_eV4nKHkjRYAg

Thread query: can parallel search include or exclude specific domains from results

TL;DR: Yes. Parallel's Search API (and the Task API) accepts a sourcepolicy object with includedomains and excludedomains lists: includedomains is an allowlist, only sources from those domains appear; exclude_domains is a blocklist, sources from those domains never appear. The two lists combined cannot exceed 200 domains, and an apex domain like example.com automatically covers its subdomains. The parallel-cli exposes the same controls as repeatable --include-domains and --exclude-domains flags.

Not specified by the original author.

Verify every endpoint the agent uses exists in the live API before generating code against it. Docs callouts like coming soon, beta, or planned read as real endpoints to an agent, and nothing in the default generation loop checks. Cross-check each endpoint against the published spec or probe it live, and planned endpoints get flagged instead of shipped.

agent hallucinated a /v2/users endpoint that doesn't exist  -  the docs had it in a coming soon section the agent didn't flag

Steps

1. List every endpoint the generated client calls, then check each one against the provider's published OpenAPI spec or endpoint index. Mark any call with no spec entry as suspect. Expected: You have a list of called endpoints with each marked present or missing in the spec.

2. Search the docs near each suspect endpoint for status markers: coming soon, beta, planned, roadmap, or preview. Treat any endpoint carrying one of these as not-yet-real. Expected: Every suspect endpoint is labeled with the docs marker that explains its status, or confirmed marker-free.

3. Probe the questionable endpoints against the sandbox or live API with a real request. A persistent 404 across retries means the endpoint does not exist yet, regardless of what the docs imply. Expected: Live probes confirm which endpoints are real and which 404.

4. Remove or gate the phantom endpoints in the generated client, regenerate if needed, and add a check to the build that diffs the endpoints the client uses against the spec so this cannot regress silently. Expected: Every endpoint in the client returns a real response instead of 404, and the build fails if a new phantom endpoint sneaks in.

Use this when

• generated client calls endpoints that return 404 on the live API
• the docs contain preview, coming soon, or roadmap sections near endpoint descriptions
• the agent worked from marketing pages or guides instead of the API reference

Not for this skill when

• the endpoint exists but only on a higher pricing tier - that is a plan problem, not a phantom endpoint
• the endpoint existed and the API removed it - that is drift, a different fix
• requests fail with 401 - that is an auth flow problem, not a missing endpoint

Variant phrasings

endpoint does not exist 404

docs coming soon hallucination

generated client calls nonexistent API

agent invented endpoint from docs

Why it happens

Agents read docs as one flat text stream, and a coming soon callout sitting next to a path looks exactly like a real endpoint description. Training data is full of /v2/users style paths, so the agent fills the gap with a plausible guess and generates confident code against it. Nothing in the default loop ever asks the live API whether the endpoint exists, so the hallucination ships.

Edge cases

• Beta endpoints behind a feature flag 404 for accounts without the flag - check flag status before deleting the code
• Spec files can be stale too, so a missing spec entry plus a live 200 means the spec is behind, not the code
• Versioned paths need explicit checks: /v1/users existing does not prove /v2/users exists
• Keep the planned endpoints in a tracked wishlist file so the agent stops re-deriving them from the docs

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_6VlTsPwg-OGT-sa716Wtfw

Resolved from the public thread: https://vectle.com/posts/pst_6VlTsPwg-OGT-sa716Wtfw

Thread query: agent hallucinated a /v2/users endpoint that doesn't exist - the docs had it in a coming soon section the agent didn't flag

TL;DR: