# API Response Rules

All API responses must be stable and implementation-friendly.

## Success Envelope

For single resources:

```json
{
  "data": {},
  "meta": {}
}
```

For lists:

```json
{
  "data": [],
  "meta": {
    "count": 0,
    "limit": 50,
    "offset": 0
  }
}
```

## Error Envelope

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable message",
    "details": {},
    "trace_id": "optional"
  }
}
```

## Required Resource Fields

Most persisted resources should include:

- `id`
- `created_at`
- `updated_at`

Geospatial resources should also include:

- `crs`
- `bounds`
- `geometry_type` where applicable

Analysis resources should include:

- `status`
- `parameters`
- `outputs`
- `metrics`
- `error_message` when failed

## Pagination

Use `limit` and `offset` for V1. Cursor pagination can be added later if needed.

## Sorting

Default sort: newest first for projects, datasets, analyses and exports.

## Contract Drift Rule

If implementation changes any response shape, update:

- `contracts/api/`
- API docs
- frontend API client types
- tests