> ## 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.

# Calling the API

> Request format, authentication, and response handling

<Note>**Research Preview** — APIs may change. [GitHub](https://github.com/AstralProtocol)</Note>

# Calling the API

This guide covers the mechanics of making requests to Astral — how to format inputs, what comes back, and how to handle errors.

## Base URL

| Environment       | URL                                 |
| ----------------- | ----------------------------------- |
| Staging (testnet) | `https://staging-api.astral.global` |
| Local development | `http://localhost:3004`             |

See [Local development](/guides/local-development) for setup instructions.

## Request format

All compute endpoints accept `POST` requests with a JSON body. The required fields depend on the operation, but every request needs a `chainId` to identify which chain to sign for.

### Distance, length

```json theme={null}
{
  "from": { "type": "Point", "coordinates": [2.2945, 48.8584] },
  "to": { "type": "Point", "coordinates": [2.3522, 48.8566] },
  "chainId": 84532
}
```

### Contains, intersects

```json theme={null}
{
  "container": {
    "type": "Polygon",
    "coordinates": [[[2.28, 48.85], [2.30, 48.85], [2.30, 48.87], [2.28, 48.87], [2.28, 48.85]]]
  },
  "geometry": { "type": "Point", "coordinates": [2.2945, 48.8584] },
  "chainId": 84532
}
```

### Optional fields

| Field       | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `schema`    | EAS schema UID — required if you plan to submit the result onchain |
| `recipient` | Ethereum address to set as the attestation recipient               |

## Geographic feature inputs

You can pass geographic features in four formats:

### Raw GeoJSON

A GeoJSON geometry object directly in the request:

```json theme={null}
{
  "from": { "type": "Point", "coordinates": [2.2945, 48.8584] }
}
```

### UID string

A reference to an onchain location attestation:

```json theme={null}
{
  "from": "0xabc123...def456"
}
```

### UID + URI (offchain attestation)

A reference to an offchain attestation stored on IPFS or another location:

```json theme={null}
{
  "from": { "uid": "0xabc123...", "uri": "ipfs://Qm..." }
}
```

### Inline signed attestation

A full offchain attestation object:

```json theme={null}
{
  "from": { "attestation": { "uid": "0x...", "schema": "0x...", "data": "0x..." } }
}
```

## Authentication

No authentication is currently required. Rate limits apply by IP address (100 requests/hour for unauthenticated clients). Wallet-based authentication with higher limits is planned.

## Response format

A successful response includes the computed result, proof of computation, and a pre-signed attestation for optional onchain submission.

```json theme={null}
{
  "result": 4520.37,
  "units": "meters",
  "operation": "distance",
  "timestamp": 1706400000,
  "inputRefs": [
    "0xabc123...input_a_hash",
    "0xdef456...input_b_hash"
  ],
  "attestation": {
    "uid": "0x...",
    "schema": "0x...",
    "attester": "0x...",
    "recipient": "0x...",
    "data": "0x...",
    "signature": "0x..."
  },
  "delegatedAttestation": {
    "signature": "0x7f8e9d...tee_signature",
    "attester": "0x590fdb53ed3f0B52694876d42367192a5336700F",
    "deadline": 1706403600
  }
}
```

Here is what each field means:

* **`result`** — The computed answer. A number for distance/area/length, a boolean for contains/within/intersects.
* **`units`** — Unit of measurement (for numeric results). `"meters"` or `"square_meters"`.
* **`operation`** — The spatial operation that was performed.
* **`timestamp`** — Unix timestamp of when the computation ran.
* **`inputRefs`** — Hashes of the input geographic features. These let you verify which inputs were used in the computation.
* **`attestation`** — The full EAS attestation data, including the TEE's cryptographic signature.
* **`delegatedAttestation`** — A pre-signed attestation ready for onchain submission via EAS. The `deadline` indicates when the signature expires.

## Error handling

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

```json theme={null}
{
  "type": "https://staging-api.astral.global/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Field 'from' must be a valid GeoJSON geometry or attestation UID"
}
```

### Common error types

| Type                    | Status | What it means                                         |
| ----------------------- | ------ | ----------------------------------------------------- |
| `invalid-input`         | 400    | Bad request data, missing fields, or invalid geometry |
| `attestation-not-found` | 404    | The UID does not exist on the specified chain         |
| `verification-failed`   | 401    | Signature verification failed                         |
| `computation-error`     | 500    | The PostGIS operation failed                          |
| `rate-limited`          | 429    | Too many requests — wait and retry                    |

### Handling errors in code

```typescript theme={null}
const response = await fetch('https://staging-api.astral.global/compute/v0/distance', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    from: { type: 'Point', coordinates: [2.2945, 48.8584] },
    to: { type: 'Point', coordinates: [2.3522, 48.8566] },
    chainId: 84532
  })
});

if (!response.ok) {
  const error = await response.json();
  console.error(`${error.title}: ${error.detail}`);
  return;
}

const result = await response.json();
console.log(`Distance: ${result.result} ${result.units}`);
```

## Full example: curl

```bash theme={null}
curl -X POST https://staging-api.astral.global/compute/v0/contains \
  -H "Content-Type: application/json" \
  -d '{
    "container": {
      "type": "Polygon",
      "coordinates": [[[2.28, 48.85], [2.30, 48.85], [2.30, 48.87], [2.28, 48.87], [2.28, 48.85]]]
    },
    "containee": { "type": "Point", "coordinates": [2.2945, 48.8584] },
    "chainId": 84532
  }'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Agent integration" icon="robot" href="/guides/agent-integration">
    Use Astral as a spatial oracle in agent workflows
  </Card>

  <Card title="Blockchain integration" icon="link-simple" href="/guides/blockchain-integration">
    Submit signed results onchain via EAS
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/overview">
    Full endpoint documentation
  </Card>
</CardGroup>