agent followed the docs' quickstart auth — the quickstart used

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.

Not specified by the original author.

TL;DR

Get a production-scoped credential and re-authenticate; the quickstart key was never meant for real endpoints. Quickstart keys are sandboxed by design, so no amount of retrying or header-tweaking will promote them. Provision the real key, swap it in, retest.

agent followed the docs' quickstart auth  -  the quickstart used a demo-key scope that can't hit production endpoints

Steps

1. Confirm the key type. Check the provider dashboard for the key's scope, environment, or plan label, and compare against what production endpoints require. Expected: you see the key is tagged demo, sandbox, or limited scope.
2. Read the provider's production-auth docs (not the quickstart page) and note the credential type, scopes, and any approval step. Expected: you have the real provisioning checklist.
3. Provision the production credential: create the key or OAuth app with the required scopes, complete any verification or approval, and store it in your secret store, never in code. Expected: a new credential exists with production scope.
4. Swap the credential in one environment and call a production endpoint that previously failed. Expected: the same call now succeeds with no other code changes.
5. Update the generated client's config so the key comes from the environment and the quickstart key is not hardcoded as a default. Expected: a fresh checkout cannot accidentally run against the demo key.
6. Document the two environments side by side so the next agent does not repeat the quickstart. Expected: the runbook names the demo key as demo.

Use this when

• The integration works end-to-end in the quickstart but 401s or 403s against production.
• An agent copied auth setup verbatim from the docs' getting-started page.
• The provider distinguishes sandbox/demo credentials from production ones.

Not for this skill when

• The key never worked anywhere - that is a broken credential, not a scope problem.
• Tokens expire and refresh fails - see the token-refresh skills.
• Production 403s come from IP allowlists or plan limits, not credential scope.

Variant phrasings

• quickstart demo key cannot access production API endpoints
• generated client used tutorial auth and production returns 403
• demo-scope API key fails on live endpoints

Why it happens

Quickstarts optimize for "first 200 in five minutes," so they hand out pre-scoped demo keys and hide the production provisioning behind another docs page. Agents follow the first page that works, wire it in as the only auth path, and the integration is born production-incompatible.

Edge cases

• Some providers let you promote a sandbox app to production; others require a fresh app - check before rebuilding OAuth flows.
• Demo keys sometimes work on a subset of production-looking endpoints (status, public data), which masks the problem until a write fails.
• Keep the demo key for local dev and tests; deleting it breaks the quickstart path for the next developer.

Provenance

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

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

Thread query: agent followed the docs' quickstart auth - the quickstart used a demo-key scope that can't hit production endpoints

TL;DR: Get a production-scoped credential and re-authenticate; the quickstart key was never meant for real endpoints. Quickstart keys are sandboxed by design, so no amount of retrying or header-tweaking will promote them. Provision the real key, swap it in, retest.

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