> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mireye.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /v1/ask-site

> Ask a registered polygon a question — one model call over a dossier that was screened once.

Answers a question about a site registered with
[`POST /v1/sites`](/api-reference/sites). One model call over the persisted
dossier — **it never re-fetches**, because the sieve already ran at
registration.

```bash theme={null}
curl -s https://api.mireye.com/v1/ask-site \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "site_id": "'"$SITE_ID"'",
    "question": "What limits how much of this site is buildable?"
  }' | jq
```

`question` is capped at 2,000 characters. The answer comes back with
citations, the same as [`/v1/ask`](/api-reference/ask).

## Why this exists

Ask ten questions about one parcel through `/v1/ask` and you pay for ten
planner runs and ten rounds of fetching over the same ground. Through a site,
you pay for the screen once and then ten cheap reads against it.

That maps onto how diligence actually goes: a site gets picked up, gets
interrogated from several angles over days, and gets dropped or advanced.
The expensive part should happen once, at the front.

## Timing

If the site is still `building`, you get a `202` — poll
[`GET /v1/sites/{site_id}`](/api-reference/sites#poll) until it reports
`ready`. Registration runs a real screen across the polygon and takes
minutes, not seconds.

**10 credits** per question.

## Failures

| `error`                 | HTTP | Meaning                                                                                                                                                       | Retryable                       |
| ----------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `site_not_found`        | 404  | No ready dossier for that `site_id`.                                                                                                                          | no — register the polygon first |
| `ask_answer_incomplete` | 502  | The model did not return a complete answer — it ran out of output budget mid-answer, or omitted a required part of it. The credits are refunded, best-effort. | yes                             |
| `ask_question_refused`  | 422  | The model declined to answer. Deterministic — rephrase rather than retry. The credits are refunded, best-effort.                                              | no                              |

An incomplete answer is stochastic rather than a property of the question, so
a retry usually succeeds. It is never returned as a `200` with an empty
`answer` — if you have code branching on an empty answer string, you can drop
it.

## Scope

The dossier is a snapshot from `built_at`. It does not refresh itself. For a
site you are tracking over months, re-register the polygon to rebuild —
same geometry, same `site_id`.


## OpenAPI

````yaml POST /v1/ask-site
openapi: 3.1.0
info:
  title: Mireye Earth
  description: >-
    Provenance-tagged geospatial data for US coordinates. POST /v1/fetch for
    deterministic field values (POST /v1/fetch/batch for up to 25 locations at
    once); POST /v1/ask for natural-language Q&A; GET /v1/meta/fields for the
    catalog.
  version: 0.16.0
servers: []
security: []
paths:
  /v1/ask-site:
    post:
      summary: Ask Site
      description: >-
        Answer a question about a registered site — ONE Opus call over the

        persisted dossier. Never re-fetches; the sieve ran once at register
        time.
      operationId: ask_site_v1_ask_site_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AskSiteRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AskSiteRequest:
      properties:
        site_id:
          type: string
          maxLength: 64
          minLength: 4
          title: Site Id
        question:
          type: string
          maxLength: 2000
          minLength: 1
          title: Question
      type: object
      required:
        - site_id
        - question
      title: AskSiteRequest
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````