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

# API Overview

> REST APIs for location proof verification and geospatial operations

<Warning>
  **Research Preview** — This API specification is under development.
</Warning>

# API reference

Astral provides two REST APIs for working with location proofs and geospatial data:

| API             | Purpose                           | Base URL      |
| --------------- | --------------------------------- | ------------- |
| **Verify API**  | Verify location proofs and stamps | `/verify/v0`  |
| **Compute API** | Verifiable geospatial operations  | `/compute/v0` |

<Note>
  The **Records API** (query location attestations across chains) is not yet integrated into the service. See the [roadmap](/resources/roadmap) for timeline.
</Note>

<CardGroup cols={2}>
  <Card title="Verify API" icon="shield-check" href="/api-reference/verify/stamp">
    Verify stamps, evaluate proofs, list plugins
  </Card>

  <Card title="Compute API" icon="calculator" href="/api-reference/compute/distance">
    Distance, containment, proximity checks with signed attestations
  </Card>
</CardGroup>

***

## Base URLs

```
https://staging-api.astral.global/verify/v0
https://staging-api.astral.global/compute/v0
```

## Authentication

The hosted staging service is currently open: the **public tier needs no API key**. Supplying an API key as a header raises your rate limit:

```bash theme={null}
# Either header works
-H "X-API-Key: your-api-key"
-H "Authorization: Bearer your-api-key"
```

### Rate limits

| Tier          | Limit                | How to get                                                            |
| ------------- | -------------------- | --------------------------------------------------------------------- |
| **Public**    | 100 requests/hour    | Default — no API key required                                         |
| **Developer** | 1,000 requests/hour  | Email [contact@astral.global](mailto:contact@astral.global) for a key |
| **Internal**  | 10,000 requests/hour | Astral team only                                                      |

<Note>
  Rate-limit tiers are an evolving part of the Research Preview. The public tier is open today; authenticated tiers are being rolled out.
</Note>

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1706403600
```

## Input types

All compute endpoints accept geometry inputs in these formats:

| Format         | Description                                | Example                                           |
| -------------- | ------------------------------------------ | ------------------------------------------------- |
| Onchain UID    | Onchain attestation reference              | `{"uid": "0xabc123..."}`                          |
| GeoJSON        | Raw geometry                               | `{"type": "Point", "coordinates": [2.29, 48.85]}` |
| UID + URI      | Offchain attestation (not yet implemented) | `{"uid": "0xabc...", "uri": "ipfs://Qm..."}`      |
| Verified proof | Full verified proof response object        | `{"verifiedProof": { ... }}`                      |

See [Input](/api-reference/types#input) for the full type definition.

## Response format

### Numeric operations (distance, area, length)

```json theme={null}
{
  "result": 523.45,
  "units": "meters",
  "operation": "distance",
  "timestamp": 1706400000,
  "inputRefs": ["0x...", "0x..."],
  "attestation": {
    "schema": "0x...",
    "attester": "0x...",
    "recipient": "0x...",
    "data": "0x...",
    "revocable": true,
    "refUID": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "signature": "0x..."
  },
  "delegatedAttestation": {
    "signature": "0x...",
    "attester": "0x...",
    "deadline": 1706403600,
    "nonce": 0
  }
}
```

See [NumericComputeResponse](/api-reference/types#numericcomputeresponse) and [BooleanComputeResponse](/api-reference/types#booleancomputeresponse) for the full type definitions.

### Boolean operations (contains, within, intersects)

Same shape, but `result` is `true`/`false` and there is no `units` field.

## Error format

Errors follow [RFC 7807](https://tools.ietf.org/html/rfc7807) (Problem Details for HTTP APIs):

```json theme={null}
{
  "type": "https://astral.global/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "geometry field is required"
}
```

### Error types

| Type              | Status | Description                                        |
| ----------------- | ------ | -------------------------------------------------- |
| `bad-request`     | 400    | Malformed request body                             |
| `invalid-input`   | 400    | Bad request data, missing fields, invalid geometry |
| `validation`      | 400    | Input validation failed                            |
| `unauthorized`    | 401    | Invalid or missing API key                         |
| `not-implemented` | 501    | Requested operation or plugin not yet supported    |
| `internal`        | 500    | Internal server error                              |
| `database`        | 500    | Database operation failed                          |
| `rate-limited`    | 429    | Too many requests — check rate limit headers       |

## Chain configuration

The **Attester Address** is the address that signs delegated attestations. Resolver contracts must verify attestations come from this address.

| Chain        | Chain ID | EAS                                          | Schema Registry                              | Attester Address                             |
| ------------ | -------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
| Base Sepolia | 84532    | `0x4200000000000000000000000000000000000021` | `0x4200000000000000000000000000000000000020` | `0x590fdb53ed3f0B52694876d42367192a5336700F` |

## Endpoints

### Verify API

<CardGroup cols={2}>
  <Card title="POST /verify/v0/stamp" href="/api-reference/verify/stamp">
    Verify a single stamp's internal validity
  </Card>

  <Card title="POST /verify/v0/proof" href="/api-reference/verify/proof">
    Verify a proof with cross-correlation analysis
  </Card>

  <Card title="GET /verify/v0/plugins" href="/api-reference/verify/plugins">
    List available verification plugins
  </Card>
</CardGroup>

### Compute API

<CardGroup cols={2}>
  <Card title="POST /compute/v0/distance" href="/api-reference/compute/distance">
    Distance between two geometries
  </Card>

  <Card title="POST /compute/v0/area" href="/api-reference/compute/area">
    Area of a polygon
  </Card>

  <Card title="POST /compute/v0/length" href="/api-reference/compute/length">
    Length of a line
  </Card>

  <Card title="POST /compute/v0/contains" href="/api-reference/compute/contains">
    Is geometry B inside geometry A?
  </Card>

  <Card title="POST /compute/v0/within" href="/api-reference/compute/within">
    Is point within radius of target?
  </Card>

  <Card title="POST /compute/v0/intersects" href="/api-reference/compute/intersects">
    Do geometries overlap?
  </Card>
</CardGroup>