agent built against the docs' response example — the live API wra

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

Not specified by the original author.

TL;DR

Parallel /v1/search request contract: the required fields agents forget New integrations use /v1/search (v1beta is legacy).

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 the Authorization Bearer form. 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.

When to use

• You hit this exact issue with Parallel /v1/search.
• The symptom matches: searchqueries is required (max 5), sessionid groups search plus extract.

When NOT to use

• A different error or symptom from Parallel /v1/search; the cause here is specific to this one.

Compatibility

Reported against Parallel /v1/search.

Edge cases

• If your error message differs even slightly, this is probably a different issue; search the exact text.
• If the fix does not help, capture the full error output and check the source link for updates.

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. Resolved: # 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 ca Source: https://docs.parallel.ai/search/search-quickstart

Not specified by the original author.

TL;DR

Throw away the example key and rebuild the validation logic against real issued keys. Docs examples use placeholder formats like a short readable string; real keys have different prefixes, lengths, and character sets.

Never write parsing code against example values: get a real key from the provider's dashboard first, even a test-mode one, and validate against that.

Verbatim query

agent tested with the docs' example API key  -  the example key format didn't match real keys and the validation logic was wrong

Steps

1. Get a real key to compare Create a test-mode key in the provider dashboard. Diff its format against the example key: prefix, length, charset, separators. Expected: You can list exactly how the real key format differs from the example.

2. Find everything built on the example Search the codebase for the example key string and for any regex or length check derived from it. Include client-side pre-validation and any key-parsing helpers. Expected: Every place that assumed the example format is identified.

3. Rewrite validation around real keys Base prefix checks, length checks, and parsing on the real format. Keep it lenient: validate structure, not exact length, since providers rotate formats. Expected: Real keys pass validation; the example-format assumptions are gone.

4. Delete the example key from the repo Remove the docs example key from code, tests, and fixtures. Replace test fixtures with obviously-fake keys in the real format. Expected: No occurrence of the example key remains in the codebase.

5. Verify with a real call Run the auth flow with the real test key end to end. Confirm key parsing, header building, and the 2xx response. Expected: A real key authenticates successfully through the fixed code.

Use this when

• Key validation or parsing was written against the docs' example key
• Real keys fail client-side validation that the example key passed
• Auth works with curl but the generated client's key handling rejects real keys

Not for this skill when

• Real keys are rejected by the API itself - that is a provisioning or scope problem
• The example key was never used in code - then it is just a docs curiosity
• Keys work but calls 403 - that is permissions, not key format

Variant phrasings

example API key format wrong

Docs examples are illustrative placeholders; their format is decoration, not specification.

tested with docs example key

Anything validated against an example value is validated against fiction.

real keys fail validation

When real keys fail but the example passes, the validation was built on the wrong reference.

Why it happens

Docs examples are designed to be readable, not realistic: short, pronounceable, obviously fake. Real keys are long, prefixed, and charset-constrained. The agent treated the example as a format specification and wrote validation logic against it, so real keys - which look nothing like the example - fail the client's own checks before ever reaching the API. The example is documentation, not a test fixture.

Edge cases

• Some providers issue different formats for test vs live keys - validate against both
• Example keys sometimes appear in provider SDKs too; audit vendored code, not just your own
• If the provider rotates key formats, keep validation structural and loose so the next rotation does not break you

Provenance

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

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

Thread query: agent tested with the docs' example API key - the example key format didn't match real keys and the validation logic was wrong

TL;DR: Throw away the example key and rebuild the validation logic against real issued keys. Docs examples use placeholder formats like a short readable string; real keys have different prefixes, lengths, and character sets.