> ## 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/sites

> Register an area of interest once, screen it once, then ask it questions cheaply for as long as it exists.

Everything else in the API answers about a **point**. A real project is a
**polygon** — a parcel, an assemblage, a search area — and screening one
properly means running the full sieve across its extent, which takes minutes,
not milliseconds.

So sites split the work in two. Register the polygon once and pay for the
screen once. After that, questions against the resulting dossier are a single
model call with no re-fetching, at [`POST /v1/ask-site`](/api-reference/ask-site).

## Register

The body is a GeoJSON `Polygon` or `MultiPolygon` in WGS84:

```bash theme={null}
curl -s https://api.mireye.com/v1/sites \
  -H "Authorization: Bearer $MIREYE_API_TOKEN" \
  -H 'content-type: application/json' \
  -d '{
    "site": {
      "type": "Polygon",
      "coordinates": [[
        [-96.8020, 32.7740], [-96.7920, 32.7740],
        [-96.7920, 32.7800], [-96.8020, 32.7800],
        [-96.8020, 32.7740]
      ]]
    }
  }'
```

```json theme={null}
{
  "site_id": "…",
  "status": "building",
  "message": "Screening this site (runs once). Poll GET /v1/sites/{site_id}."
}
```

Registration returns `202 building` and runs the sieve off the request loop.
Limits: **200,000 acres** (about 313 square miles) and **20,000 vertices**.
A malformed geometry is a `422` and is rejected before metering, so a bad
polygon costs you nothing.

`site_id` is a hash of the geometry, which makes registration **idempotent** —
the same polygon always resolves to the same site, and concurrent
registrations run the sieve exactly once.

## Poll

```bash theme={null}
curl -s "https://api.mireye.com/v1/sites/$SITE_ID" \
  -H "Authorization: Bearer $MIREYE_API_TOKEN"
```

```json theme={null}
{
  "site_id": "…",
  "status": "ready",
  "site_acres": 61.4,
  "site_extent": [-96.8020, 32.7740, -96.7920, 32.7800],
  "built_at": "2026-08-26T07:31:04+00:00"
}
```

`GET /v1/sites/{site_id}` is **unmetered** — poll it as often as you like.
Statuses are `building`, `ready`, and `failed`; an unknown id is a
`404 site_not_found`.

## What it costs

Registration bills **10 credits** on every call past geometry validation,
including the idempotent reply for a site that is already `ready`. That is
deliberate: polling registration would otherwise be a free status endpoint,
and the unmetered `GET` above already is one.

The pattern that saves money: register once, poll the `GET`, then ask
questions.

<CardGroup cols={2}>
  <Card title="POST /v1/ask-site" icon="message" href="/api-reference/ask-site">
    Ask the registered dossier a question.
  </Card>

  <Card title="Pricing" icon="calculator" href="/pricing">
    How sites price against per-point fetches.
  </Card>
</CardGroup>


## OpenAPI

````yaml POST /v1/sites
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/sites:
    post:
      summary: Register Site
      description: |-
        Register/bootstrap a site: validate the polygon, kick the dossier build
        ONCE (the slow sieve + fetch), persist it. Idempotent — same polygon →
        same site_id. Questions then go to POST /v1/ask-site with the site_id.
      operationId: register_site_v1_sites_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SiteRegisterRequest'
        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:
    SiteRegisterRequest:
      properties:
        site:
          additionalProperties: true
          type: object
          title: Site
      type: object
      required:
        - site
      title: SiteRegisterRequest
    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

````