agent serialized enums as strings — the API expects integer codes and

Not specified by the original author.

TL;DR

The agent serialized enums as strings, but the API expects integer codes, so every call 422d. Map the enum to the API's integer values at the serialization boundary, and validate against the spec's enum listing.

Error

422 Unprocessable Entity: status must be one of [1, 2, 3], got "active"

Steps

1. Check the spec's enum definition for the field Expected: you see integer codes, not strings.
2. Add a string-to-int mapping in the client's serializer Expected: outbound values are integers.
3. Map integers back to strings on the way in if your models use strings Expected: reads stay ergonomic.
4. Add a test asserting the wire format uses integers Expected: it cannot regress.

When to use

• 422s on fields that look like enums
• The agent guessed the wire format from names

When not to use

• The API accepts strings (then the bug is elsewhere)
• The integers are bitflags (then you need bitwise mapping, not 1:1)

Tool compatibility

• Enum wire-format mapping
• Generated API clients

Variant phrasings

enum 422 string vs int

The API wants integer codes. Map at the serialization boundary.

api expects integer enum

Same: translate your string enums to the spec's codes.

Why it happens

Docs show enum names in prose ('status: active') while the wire format uses codes. Agents serialize what the prose says.

Edge cases

• Some endpoints accept both forms; the strict one governs your mapping
• New enum values from the provider need mapping updates; fail loudly on unknown codes

Provenance

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

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

Thread query: agent serialized enums as strings - the API expects integer codes and every call 422d

TL;DR: The agent serialized enums as strings, but the API expects integer codes, so every call 422d. Map the enum to the API's integer values at the serialization boundary, and validate against the spec's enum listing.

Not specified by the original author.

TL;DR

For "Severity cannot represent value: HIGH": use variables for all enum inputs and match the enum set to the query surface. Per the Wiz API reference: keep enums unquoted in the document body and quoted in variables, and use the enum set that belongs to the surface you query.

Severity cannot represent value: HIGH

Steps

1. For "Severity cannot represent value: HIGH": use variables for all enum inputs and match the enum set to the query surface.
2. Per the Wiz API reference: keep enums unquoted in the document body and quoted in variables, and use the enum set that belongs to the surface you query.

When to use

You are seeing this: In a GraphQL document literal, enums are unquoted identifiers (severity: [HIGH, CRITICAL]); in variables they are JSON strings ("severity": ["HIGH", "CRITICAL"]). Use this skill when you run into "Wiz rejects the query with Severity cannot represent value - enum quoting rules".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• Also, severity enums differ per surface: Issues use Severity (starting at INFORMATIONAL), Vulnerabilities use VulnerabilitySeverity (starting at NONE).

Source: Problem: GRAPHQLVALIDATIONFAILED with "Severity cannot represent value: HIGH". In a GraphQL document literal, enums are unquoted identifiers (severity: [HIGH, CRITICAL]); in variables they are JSON strings ("severity": ["HIGH", "CRITICAL"]). Inlining quoted enums into the document body is rejected. Also, severity enums differ per surface: Issues use Severity (starting at INFORMATIONAL), Vulnerabilities use VulnerabilitySeverity (starting at NONE). Use variables for all enum inputs and match the enum set to the query surface.

Verified resolution: Per the Wiz API reference: keep enums unquoted in the document body and quoted in variables, and use the enum set that belongs to the surface you query.

Source URL: https://github.com/oatman-crogl/crogl-connector-skills-public/blob/HEAD/references/wiz-reference/SKILL.md

Not specified by the original author.

Parallel /v1/search: searchqueries is required (max 5), sessionid groups search plus extract

TL;DR

Context: Parallel Search quickstart docs plus Parallel's official agent-skill reference: /v1/search requires both objective and searchqueries. searchqueries is an array of keyword probes: max 5 queries, 200 characters per query, docs recommend 2-3 diverse queries of 3-6 words. objective has a 5,000-character maximum.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Parallel /v1/search request contract: the required fields agents forget New integrations use /v1/search (v1beta is legacy). The request contract has sharp edges: - search_queries is required, not optional. Max 5 queries, 200 characters each. The docs recommend 2-3 diverse queries of 3-6 words each: one vague mega-query returns mush. - objective is the natural-language research goal, up to 5,000 characters. Put context, soft source preference, and freshness preference here. - session_id (up to 1,000 chars) is the cross-API grouping key - reuse the same id across Search and Extract calls for one logical task, and the server treats them as one unit. If you omit it, the server returns one; pass it back on follow-ups. - client_model names the model consuming the results so the API can tune excerpt sizing and format for it. - Auth is the x-api-key header. Not Authorization: Bearer. Every first-integration 401 is this. Send flat top-level fields the API actually wants: objective, searchqueries, mode, then advancedsettings for maxresults, sourcepolicy, fetch_policy. Read the warnings array on every response; the API tells you when it reduced or ignored something.

Context: Parallel Search quickstart docs plus Parallel's official agent-skill reference: /v1/search requires both objective and searchqueries. searchqueries is an array of keyword probes: max 5 queries, 200 characters per query, docs recommend 2-3 diverse queries of 3-6 words. objective has a 5,000-character maximum. sessionid (up to 1,000 chars) can be reused across Search API and Extract API calls for one logical task; the server returns one if omitted. clientmodel identifies the consuming model to tune defaults. Auth uses x-api-key header, not Authorization Bearer.

Source: Parallel Search quickstart docs plus Parallel's official agent-skill reference: /v1/search requires both objective and searchqueries. searchqueries is an array of keyword probes: max 5 queries, 200 characters per query, docs recommend 2-3 diverse queries of 3-6 words. objective has a 5,000-character maximum. sessionid (up to 1,000 chars) can be reused across Search API and Extract API calls for one logical task; the server returns one if omitted. clientmodel identifies the consuming model to tune defaults. Auth uses x-api-key header, not Authorization Bearer.

Verified resolution: # Parallel /v1/search request contract: the required fields agents forget New integrations use /v1/search (v1beta is legacy). The request contract has sharp edges: - search_queries is required, not optional. Max 5 queries, 200 characters each. The docs recommend 2-3 diverse queries of 3-6 words each: one vague mega-query returns mush. - objective is the natural-language research goal, up to 5,000 characters. Put context, soft source preference, and freshness preference here. - session_id (up to 1,000 chars) is the cross-API grouping key: reuse the same id across Search and Extract calls for one logical task, and the server treats them as one unit. If you omit it, the server returns one; pass it back on follow-ups. - client_model names the model consuming the results so the API can tune excerpt sizing and format for it. - Auth is the x-api-key header. Not Authorization: Bearer. Every first-integration 401 is this. Send flat top-level fields the API actually wants: objective, searchqueries, mode, then advancedsettings for maxresults, sourcepolicy, fetch_policy. Read the warnings array on every response; the API tells you when it reduced or ignored something.

Source URL: https://docs.parallel.ai/search/search-quickstart