# API v2

Full programmatic access to research, extraction, publications, and workspace management

`https://api.webhound.ai/api/v2`·57 endpoints·Bearer auth·JSON responses

## Authentication

All requests require an API key in the Authorization header:

```
Authorization: Bearer wh_your_api_key_here
```

Get your API key from the Account page. Keys start with `wh_`

### Response format

All endpoints return structured JSON. Every response follows this envelope:

**Success**

```
{ "success": true, "data": { ... } }
```

**Error**

```
{ "success": false, "error": "message" }
```

The `data` field contains the endpoint-specific payload — an object, array, or nested structure depending on the endpoint.

### HTTP status codes

**200** Success\n**400** Bad request\n**401** Invalid/missing key\n**402** Insufficient credits\n**403** Access denied\n**404** Not found\n**409** Conflict (wrong state)\n**500** Server error

## Workspace

### Endpoints

- **GET** `/workspace` Browse folder tree
- **GET** `/workspace/folders/:folderId` List folder contents
- **POST** `/workspace/folders` Create folder
- **PATCH** `/workspace/folders/:folderId` Rename folder
- **DELETE** `/workspace/folders/:folderId` Delete folder
- **POST** `/workspace/sessions/:sessionId/move` Move session to folder

## Session Discovery

### Endpoints

- **GET** `/sessions` List sessions
- **GET** `/sessions/search` Semantic search sessions
- **GET** `/sessions/find` Find by metadata
- **GET** `/sessions/search-documents` Text search across documents
- **GET** `/sessions/search-knowledge` Search knowledge bases
- **GET** `/sessions/search-claims` Search claims

## Session Reading

### Endpoints

- **GET** `/sessions/:sessionId` Session overview
- **GET** `/sessions/:sessionId/document` Read document
- **GET** `/sessions/:sessionId/dataset` Read dataset rows
- **GET** `/sessions/:sessionId/claims` Get claims
- **GET** `/sessions/:sessionId/tasks` Work log
- **GET** `/sessions/:sessionId/sources` Cited sources
- **GET** `/sessions/:sessionId/knowledge-base` Knowledge base
- **GET** `/sessions/:sessionId/notepad` Agent notepad
- **GET** `/sessions/:sessionId/messages` Message history
- **POST** `/sessions/:sessionId/messages` Send a message
- **GET** `/sessions/:sessionId/extraction-plan` Extraction plan
- **GET** `/sessions/:sessionId/status` Job status

## Session Management

### Endpoints

- **PATCH** `/sessions/:sessionId` Rename session
- **DELETE** `/sessions/:sessionId` Delete session

## Research

### Endpoints

- **POST** `/research` Start research
- **POST** `/research/:sessionId/budget` Add research budget
- **POST** `/research/:sessionId/audit` Add audit budget
- **POST** `/research/:sessionId/stop` Stop research
- **POST** `/research/:sessionId/resume` Resume session

## Extraction

### Endpoints

- **POST** `/extractions` Start extraction
- **POST** `/extractions/:sessionId/stop` Stop extraction
- **GET** `/extractions/:sessionId/items` Get dataset items
- **POST** `/extractions/import` Import spreadsheet
- **POST** `/extractions/fork` Fork dataset

## Pipelines

### Endpoints

- **POST** `/chains` Start pipeline
- **POST** `/chains/:chainId/pause` Pause pipeline
- **POST** `/chains/:chainId/resume` Resume pipeline

## Files

### Endpoints

- **GET** `/files` List files
- **GET** `/files/:fileId` Read file
- **POST** `/files/upload` Upload file
- **POST** `/files/attach` Attach files to session

## Publications

### Endpoints

- **POST** `/publications` Publish research
- **GET** `/publications` List publications
- **GET** `/publications/feed` Personal feed
- **GET** `/publications/:idOrSlug` Get publication
- **GET** `/publications/:id/versions` Version history
- **GET** `/publications/:id/attribution` Attribution chain
- **POST** `/publications/:id/copy` Copy to workspace
- **POST** `/publications/:id/watch` Toggle watch
- **PATCH** `/publications/:id` Update publication
- **DELETE** `/publications/:id` Delete publication

## Authors

### Endpoints

- **POST** `/authors/:authorId/follow` Toggle follow
- **GET** `/authors/:authorId` Author profile

## Account

### Endpoints

- **GET** `/account/credits` Credit balance
- **GET** `/account/usage` Spending history

## Workflows

Common multi-step patterns using the API.

### Research, Read, Publish

1. Start research

```
curl -X POST https://api.webhound.ai/api/v2/research \
  -H "Authorization: Bearer wh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "AI Governance", "query": "Research AI governance frameworks in 2026", "budget": 15 }'
   ```

2. Poll status until completed

```
curl https://api.webhound.ai/api/v2/sessions/{session_id}/status \
  -H "Authorization: Bearer wh_YOUR_KEY"
# Repeat every 10s until status = "completed"
   ```

3. Read the output document

```
curl https://api.webhound.ai/api/v2/sessions/{session_id}/document \
  -H "Authorization: Bearer wh_YOUR_KEY"
   ```

4. Read verified claims

```
curl https://api.webhound.ai/api/v2/sessions/{session_id}/claims \
  -H "Authorization: Bearer wh_YOUR_KEY"
   ```

5. Publish to community

```
curl -X POST https://api.webhound.ai/api/v2/publications \
  -H "Authorization: Bearer wh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "folder_id": "...", "title": "AI Governance Report", "license": "open" }'
   ```

### Extraction Pipeline

1. Start a multi-step pipeline

```
curl -X POST https://api.webhound.ai/api/v2/chains \
  -H "Authorization: Bearer wh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Competitor Intel", "steps": [{ "type": "research", "query": "Map competitor landscape", "budget": 10 }, { "type": "extraction", "query": "Extract company data", "budget": 5 }] }'
   ```

2. Poll status of each step

```
curl https://api.webhound.ai/api/v2/sessions/{session_id}/status \
  -H "Authorization: Bearer wh_YOUR_KEY"
   ```

3. Get the extracted dataset

```
curl https://api.webhound.ai/api/v2/extractions/{session_id}/items \
  -H "Authorization: Bearer wh_YOUR_KEY"
   ```

### Research with Audit

1. Start research

```
curl -X POST https://api.webhound.ai/api/v2/research \
  -H "Authorization: Bearer wh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Drug Policy Analysis", "query": "Analyze drug decriminalization outcomes", "budget": 20 }'
   ```

2. Wait for completion

```
# Poll /sessions/{session_id}/status until status = "completed"
   ```

3. Add audit to verify claims

```
curl -X POST https://api.webhound.ai/api/v2/research/{session_id}/audit \
  -H "Authorization: Bearer wh_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 10, "focus": "Fact-check all statistics and check source reliability" }'
   ```

4. Read audited claims with confidence scores

```
curl https://api.webhound.ai/api/v2/sessions/{session_id}/claims \
  -H "Authorization: Bearer wh_YOUR_KEY"
   ```