Valyu - Search, Answer & Deep Research

Setup

Read your credentials from ~/.gooseworks/credentials.json:

export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")

If ~/.gooseworks/credentials.json does not exist, tell the user to run: npx gooseworks login

All endpoints use Bearer auth: -H "Authorization: Bearer $GOOSEWORKS_API_KEY"

Search the web, get AI answers, extract content, and run deep research tasks.

Capabilities

• Get Status: Reference for getting deep research task status via GET /v1/deepresearch/tasks/{id}/status
• Update Task: Reference for adding follow-up instructions to a running task via POST /v1/deepresearch/tasks/{id}/update
• Cancel Task: Reference for cancelling a running task via POST /v1/deepresearch/tasks/{id}/cancel
• Delete Task: Reference for deleting a task via DELETE /v1/deepresearch/tasks/{id}/delete
• Get Batch Status: Reference for getting batch status via GET /v1/deepresearch/batches/
• List Batch Tasks: Reference for listing tasks in a batch via GET /v1/deepresearch/batches//tasks
• Cancel Batch: Reference for cancelling a batch via POST /v1/deepresearch/batches//cancel
• Search: Reference for the Valyu Search endpoint to search the web, research, and proprietary datasets via POST /v1/search
• Answer: Reference for the Valyu Answer endpoint that blends search results into AI-generated answers via POST /v1/answer
• Contents: Reference for the Valyu Contents endpoint that extracts clean, structured content from any URL via POST /v1/contents
• Create Batch: Reference for creating a new batch via POST /v1/deepresearch/batches
• Create Task: Reference for creating a new deep research task via POST /v1/deepresearch/tasks
• Add Tasks to Batch: Reference for adding tasks to a batch via POST /v1/deepresearch/batches//tasks

Usage

Get Status

Reference for getting deep research task status via GET /v1/deepresearch/tasks/{id}/status.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/status"}'

Update Task

Reference for adding follow-up instructions to a running task via POST /v1/deepresearch/tasks/{id}/update.

Parameters:

• instruction* (string) - Follow-up instruction to add to the running task. Must be submitted before the writing phase begins.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/update","body":{"query":"Updated research query"}}'

Cancel Task

Reference for cancelling a running task via POST /v1/deepresearch/tasks/{id}/cancel.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/cancel"}'

Delete Task

Reference for deleting a task via DELETE /v1/deepresearch/tasks/{id}/delete.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/tasks/{id}/delete"}'

Get Batch Status

Reference for getting batch status via GET /v1/deepresearch/batches/.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}"}'

List Batch Tasks

Reference for listing tasks in a batch via GET /v1/deepresearch/batches//tasks.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}/tasks"}'

Cancel Batch

Reference for cancelling a batch via POST /v1/deepresearch/batches//cancel.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/deepresearch/batches/{id}/cancel"}'

Search

Reference for the Valyu Search endpoint to search the web, research, and proprietary datasets via POST /v1/search.

Parameters:

• query* (string) - The query string for the search
• max_num_results (integer) - Maximum number of results to return (1-20 for standard API keys, up to 100 with a special API key)
• search_type (enum<string>) - Type of search to perform.'web' searches and returns web content. 'proprietary' uses Valyu's full-text multimodal indicies (arxiv/pubmed/proprietary academic content). 'news' searches and returns only news articles.
• fast_mode (boolean) - Enable fast mode for reduced latency but shorter results. Best for general purpose queries.
• max_price (number<float>) - Maximum price in dollars for a thousand retrievals (CPM). Only applies when provided. If not provided, adjusts automatically based on search type and max number of results.
• relevance_threshold (number<float>) - Minimum relevance score for results (0.0-1.0)
• included_sources (string[]) - List of specific sources to search (URLs, domains or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.ai/blog' or 'valyu.ai/blog'), only that specific path will be searched. For entire domains, use either the domain name (e.g., 'valyu.ai') or the base URL (e.g., 'https://valyu.ai').
• excluded_sources (string[]) - List of specific sources to exclude from search (URLs, domains, or dataset names). When a URL or domain path is provided (e.g., 'https://valyu.ai/blog' or 'valyu.ai/blog'), only that specific path will be excluded. For entire domains, use either the domain name (e.g., 'valyu.ai') or the base URL (e.g., 'https://valyu.ai').
• category (string) - Natural language category/guide phrase to help guide the search to the most relevant content. For example 'agentic use-cases
• response_length (default:short) - Controls the length of content returned per result. Can be an integer for character count or predefined values: 'short' (25k), 'medium' (50k), 'large' (100k), 'max' (full)
• country_code (string) - 2-letter ISO country code to bias search results to a specific country
• is_tool_call (boolean) - Tunes retrieval process based on whether the API is being called by an AI agent as a tool call, or a user query.
• start_date (string<date>) - Start date for time-filtered searches (YYYY-MM-DD)
• end_date (string<date>) - End date for time-filtered searches (YYYY-MM-DD)
• url_only (boolean) - When set to true, only returns URLs for results (no content). Only applies when search_type is 'web' or 'news'.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"valyu","path":"/v1/search","body":{"query":"AI agent frameworks comparison"}}'

Answer

Reference for the Valyu Answer endpoint that blends search results into AI-generated answers via POST /v1/answer.

Parameters:

• query* (string) - The search query
• system_instructions (string) - Custom instructions for AI processing
• structured_output (object) - JSON schema for structured output. When provided, enables JSON mode and returns structured data
• search_type (string) - Type of search to perform
• fast_mode (boolean) - Enable fast mode for reduced latency but shorter results. Best for general purpose queries.
• data_ma