geointel/contracts/api/response-envelope.md

API Response and Error Contract

Standard error

All API errors must use:

{
  "error": {
    "code": "STRING_CODE",
    "message": "Human readable message.",
    "details": {}
  }
}

Job response

Long-running operations return:

{
  "job_id": "uuid",
  "analysis_run_id": "uuid",
  "status": "queued",
  "status_url": "/analysis-runs/{id}"
}

Resource metadata

Resources should include:

{
  "id": "uuid",
  "created_at": "ISO-8601",
  "updated_at": "ISO-8601"
}

Pagination

List endpoints use:

{
  "items": [],
  "total": 0,
  "limit": 50,
  "offset": 0
}