Health check

GET

/v1/health

curl --request GET \
  --url https://api.satellitedata.net/v1/health

• Production (P2 onward; internal in P1).
• Staging (P2 onward).

Reports whether the API, the pgSTAC database and each upstream source answer, with the deployed release and schema version. The status page and uptime monitors poll it once a minute. It is never cached and never metered, and it answers 503 when the database is down.

Responses

200

Service answers; status shows whether any dependency is degraded.

Media typeapplication/json

Health report.

object

status

required

Ok when every check passes, degraded when an upstream or optional check fails.

string

Allowed values: ok degraded

version

required

Deployed build, as a release tag.

string

schemaVersion

Schema v1 version in force.

string

time

required

Server time.

string format: date-time

checks

required

One entry per dependency.

object

key

additional properties

string

Allowed values: ok degraded down

Example

{
  "status": "degraded",
  "version": "v1.4.2",
  "schemaVersion": "1.0.0",
  "time": "2026-10-13T08:00:00Z",
  "checks": {
    "database": "ok",
    "earth-search": "ok",
    "cmr-stac": "degraded",
    "earthdata-credentials": "ok",
    "planetary-computer": "ok"
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

429

A per-minute, concurrency, monthly or per-IP limit was hit. Retry-After says when to retry.

Media typeapplication/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "This key spent 300 of its 300 units in the current minute.",
  "instance": "/v1/process",
  "code": "rate-limited",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 17,
  "limits": {
    "unitsPerMinute": 300,
    "unitsSpentThisMinute": 300
  }
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

17

RateLimit

string

Remaining units and seconds to reset in the current window (IETF RateLimit header draft).

Example

"units";r=287;t=41

RateLimit-Policy

string

Quota policy of the caller (IETF RateLimit header draft).

Example

"units";q=300;w=60

503

The database is unreachable.

Media typeapplication/problem+json

RFC 9457 problem details. Every 4xx and 5xx response uses this shape with media type application/problem+json. The type URL opens a documentation page that explains the cause and the fix.

object

type

required

URL of the documentation page for this problem type, stable for the life of /v1.

string format: uri

title

required

Short summary of the problem type. It does not change between occurrences.

string

status

required

HTTP status code, repeated for clients that lose the status line.

integer

>= 400 <= 599

detail

required

Explanation specific to this occurrence, written for a developer.

string

instance

Path of the request that failed.

string

code

Machine-readable problem code; equals the last path segment of type.

string

/^[a-z0-9-]+$/

requestId

Request id, also sent in X-Request-Id. Quote it in support requests.

string

errors

Field-level validation failures, present on 400 and 422.

Array<object>

One field-level failure.

object

pointer

required

JSON Pointer (RFC 6901) into the request body, or the query parameter name.

string

detail

required

What is wrong with that member.

string

retryAfter

Seconds until the request can succeed; equals the Retry-After header.

integer

limits

The limit that was hit and the value requested, for example maxWidth and requestedWidth.

object

key

additional properties

number

unitsEstimated

Units the request would have cost, computed before execution.

number

error

OAuth 2.0 error code (RFC 6749 section 5.2). Present only on /oauth/token responses.

string

Allowed values: invalid_request invalid_client invalid_grant unauthorized_client unsupported_grant_type invalid_scope

error_description

OAuth 2.0 error description. Present only on /oauth/token responses.

string

message

Copy of detail for openEO clients, which read message. Present only on /v1/openeo routes.

string

key

additional properties

any

Example

{
  "type": "https://docs.satellitedata.net/problems/maintenance",
  "title": "Service unavailable",
  "status": 503,
  "detail": "The pgSTAC database did not answer within 2 seconds.",
  "instance": "/v1/health",
  "code": "maintenance",
  "requestId": "01JQ7Z3M8R5V2W6X9Y0A1B2C3D",
  "retryAfter": 60
}

Headers

X-Request-Id

string

Request id for support and logs.

Example

01JQ7Z3M8R5V2W6X9Y0A1B2C3D

Retry-After

integer

Seconds to wait before retrying.

Example

17