Explore the API with Workbench
Run live read requests and generate secret-safe curl, TypeScript, and Python examples
The API Workbench turns Y2's live OpenAPI description into a browsable endpoint catalog, parameter editor, request runner, and snippet generator.
Open Developers → API Workbench in the dashboard.
API-key access is required
New API access is available on Pro and Elite. Existing grandfathered Lite API users retain Workbench access during the grace period.
What Workbench reads from OpenAPI
The page loads /api/openapi.yaml and uses the current contract to show:
- endpoint categories, methods, paths, summaries, and operation IDs;
- required bearer scopes from
x-required-scopes; - path and query parameter descriptions, types, enums, examples, and defaults; and
- operation- or path-level server overrides, including the Intel v2 base URL.
Parameters use enum selectors, boolean toggles, and numeric or text inputs where applicable. Required path and query values are checked before a live request leaves the browser.
Use the generated reference for request bodies
The current Workbench editor does not render OpenAPI request-body fields. Use it directly for
GET, bodyless POST, and other path/query-driven operations. For profile creation, webhook
configuration, delivery updates, and other JSON-body mutations, start from the generated
endpoint reference or the relevant API guide.
Run a read request
Paste an API key
Enter a key in the password field at the top of the page. The value remains in React component
state and is added as Authorization: Bearer ... only when you run a request.
Open a category and endpoint
Categories begin collapsed. Open one such as Intel, OSINT, Reports, or News, then choose an endpoint. The row shows its method, path, scope, parameter counts, and operation ID.
Fill required values
Path parameters are always required. Required query parameters are shown separately; enable only the optional query parameters you want to send.
Run the request
Select Run request. Workbench calls the canonical production API from your browser and shows the response status and parsed body inline. JSON is formatted; non-JSON bodies are shown as text.
If a required path or query value is missing, Workbench produces a local 400 explanation instead
of sending an incomplete request. A missing key produces a local 401 prompt.
Requests use the workspace associated with the pasted key. Switching your active workspace in the app does not change the key's workspace.
Generate a copy-safe snippet
Each expanded endpoint provides curl, TypeScript, and Python tabs. The generated code:
- references
$Y2_API_KEY,process.env.Y2_API_KEY, oros.environ["Y2_API_KEY"]; - never includes the key pasted into Workbench;
- substitutes an unset required path or query value with an
UPPER_SNAKE_CASEenvironment variable; and - adds comments for the required and currently enabled query parameters, including available descriptions, types, enums, and defaults.
For example, after enabling limit without entering a value, a curl snippet can contain:
# Required:
# countryCode (path) — ISO 3166-1 alpha-2 country code
#
# Optional:
# limit (query · integer · default: 8) — Maximum results
curl "https://api.y2.dev/api/v1/osint/countries/$COUNTRY_CODE/news?limit=$LIMIT" \
-H "Authorization: Bearer $Y2_API_KEY" \
-H "Accept: application/json"Set the placeholders before running the copied command:
export Y2_API_KEY="y2_..."
export COUNTRY_CODE="UA"
export LIMIT="8"Best for one-off checks and reproducing a request in a bug report. Unset values use shell
variables such as $COUNTRY_CODE.
Use the AI Quickstart prompt
Copy prompt copies a short instruction that directs a coding agent to the canonical Agentic DX and MCP guides before it integrates Y2. It contains documentation URLs and safety guidance, not the API key entered on the page.
Use this prompt as orientation, then give the agent the exact endpoint, scope, and outcome you need.
Keep Y2_API_KEY in the agent runtime or MCP client environment—not in the prompt or tool arguments.
Know the current boundaries
| Capability | Current behavior |
|---|---|
| API target | Production server from OpenAPI; falls back to https://api.y2.dev/api/v1 |
| Path and query fields | Interactive and OpenAPI-driven |
| Request body fields | Not rendered; use endpoint reference examples |
| Live response | Status and response body |
| Response headers | Not displayed in the inline pane |
| Authentication | Bearer key required by the runner |
| x402 | Use curl or an x402 client outside Workbench |
| Saved state | Key, expanded rows, and parameter values are page component state, not durable presets |
Workbench is an integration aid, not a replacement for application-level error handling. Before shipping copied code, add timeouts, typed response handling, pagination, retry policy, and secret management appropriate to your runtime.