---
title: "Check a question before running it (Sharpen)"
method: POST
path: "/v1/assess"
tags: ["runs"]
---

# Check a question before running it (Sharpen)

`POST /v1/assess`

## Request

- Base URL: `https://api.hyperresearch.ai`
- URL: `https://api.hyperresearch.ai/v1/assess`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `hr_session`

Assesses whether a research question is specific enough to run and returns at most ONE next question, with chips, a You decide default and the assumption taken if skipped. The user’s text is never rewritten: unclear words come back as `underline` spans. Required questions come first; optional breadth questions (sources to read first, a comparison) follow once `ready`. An already-specific question is `ready` with `score` 1 and no required question. Not charged. Rate-limited per account (30 a minute, 600 a day); 429 with `Retry-After`. 404 `feature_not_enabled` where Sharpen is off.

## Request body

- AssessBody
  - `query` string, required
  - `tier` 'light' | 'deep'
  - `brief` SharpenBriefEntry[]: Settled axes (the tags under the box). Skipping a question is an entry with `source: "you_decide"`. (unresolved $ref)
  - `must_read` string[]
  - `metadata` object: The Pulse keys, as on `POST /v1/runs`: `time_window` ("last_<N>d", {"last_days": N} or {"start", "end"?}) settles the time axis; `pulse` (boolean).

## Response `200`

Assessment

- AssessResponse
  - `ready` boolean, required
  - `score` number, required
  - `missing` string[], required
  - `question` SharpenQuestion
    - `axis` string, required
    - `required` boolean, required
    - `kind` 'single' | 'multi', required
    - `text` string, required
    - `evidence` string
    - `chips` object[], required
      - `id` string, required
      - `label` string, required
    - `allow_free` true, required
    - `you_decide` object, required
      - `label` 'You decide', required
      - `assumption` string, required
    - `assumption` string, required
    - `breadth` string
  - `underline` object[]
    - `text` string, required
    - `start` integer, required
    - `end` integer, required
  - `settled_by_text` string[], required
  - `title` string, required
  - `assessed_at` string, required
  - `pulse` boolean

## Other responses

- `400`: Invalid request
- `401`: Authentication failed
- `403`: Insufficient scope or plan
- `404`: Not found
- `429`: Rate limited or over quota
- `500`: Internal error

---

[API](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api.md) · [All operations](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hyperresearch/apis/hyperresearch-cloud-api/revisions/726ef831ebf4?raw)