SCO-LDC API Reference

1Conventions

Base URL

All endpoints are served from https://sco-ldc.com. HTTPS is required; the service does not accept HTTP.

Authentication

None. sco-ldc’s API is open and does not require API keys, tokens, registration, or any other credential. Any HTTP client can call any endpoint at any time.

Methods

All endpoints accept GET requests only. There is no POST, PUT, or DELETE. This reflects the read-only nature of the service: sco-ldc retrieves data and computes from it but does not store or modify state on behalf of callers.

Parameters

All parameters are passed as URL query string parameters. There is no JSON request body. Parameter names are case-sensitive. Numeric parameters can be passed as integers (5778) or as decimals (5778.0); both are accepted. Filter codes are strings and case-sensitive.

Response format

All successful responses are JSON with HTTP status 200. The response Content-Type is application/json. All field names use snake_case (e.g., filter_code, not filterCode). Numeric fields are always JSON numbers (not strings); string fields are always JSON strings (not numbers).

URL encoding

Filter codes containing special characters (the SDSS codes use an asterisk; planet names typically contain spaces) must be URL-encoded in the request. Most HTTP client libraries handle this automatically when parameters are passed as a structured dictionary or map rather than concatenated into the URL string. If constructing URLs manually, ensure that asterisks become %2A and spaces become %20 or +.

2Stability & versioning

The API described here is treated as a stable contract. Once a caller integrates with sco-ldc, the following are guaranteed:

• Existing parameter names will not be renamed
• Existing response field names will not be renamed
• Existing filter codes will not be reassigned to different filters
• Existing semantics will be preserved (which model is the default, which endpoint serves which path, etc.)

Additions are not considered breaking and may happen without coordination:

• New endpoints may be added at any time
• New optional parameters may be added to existing endpoints
• New response fields may be added to existing responses (callers should not fail if they encounter unknown fields)

3Endpoints overview

Typical integration flow

1. (Optional, at startup or once per session.) Call /api/filters once to discover what filters and models are available, with their grid ranges. Cache the result locally.
2. (Optional, per target.) Call /api/resolve?planet=<NAME> to fetch host-star T_eff/logg/[Fe/H] from a planet or TOI name.
3. (Per LDC requested.) Call /api/compute?teff=…&logg=…&feh=…&filter=…&model=… to obtain u₁ and u₂.

4GET /api/health

Returns a status snapshot. Useful for liveness checks and for verifying that the underlying data sources are fresh before relying on a lookup.

Required parameters: none. · Optional parameters: none.

Response (HTTP 200)

{
  "status": "ok",
  "version": "3.1.0",
  "freshness": "ok",
  "tables": {
    "tableab.dat": 179645,
    "table5.dat": 574,
    "CBBQUADRATIC.txt": 7695
  },
  "filter_count": 26,
  "nea_cache":    { "count": 6287, "refreshed_utc": "2026-06-03 17:00 UTC" },
  "exofop_cache": { "count": 7934, "refreshed_utc": "2026-06-03 17:00 UTC" }
}

Field semantics

Notes for callers

• The freshness field is the recommended signal to monitor. Callers do not need to act on ‘stale’ programmatically — the LDC computation continues to work — but it may be useful for diagnostic surfaces.
• Cache row counts grow over time as NEA and ExoFOP add new entries. Exact numbers are informational.

5GET /api/filters

Returns the catalog of filters available and, per filter, which stellar atmosphere models are populated along with their parameter grid ranges. Calling /api/filters is the authoritative way to discover what’s currently supported; new filters or new model coverage can appear in future versions.

Required parameters: none. · Optional parameters: none.

Response (HTTP 200, abbreviated to one filter entry)

{
  "filters": [
    {
      "code": "V",
      "name": "Johnson V",
      "category": "Johnson-Cousins",
      "source": "CB2011",
      "citation": "Claret & Bloemen (2011, A&A 529, A75)",
      "models": [
        {
          "model": "ATLAS",
          "model_key": "ATLAS",
          "teff_min": 3500.0, "teff_max": 50000.0,
          "logg_min": 0.0,    "logg_max": 5.0,
          "feh_min":  -5.0,   "feh_max":  1.0,
          "feh_fixed": false,
          "n_points": 7813
        },
        {
          "model": "PHOENIX",
          "model_key": "PHOENIX",
          "teff_min": 2000.0, "teff_max": 9800.0,
          "logg_min": 3.5,    "logg_max": 5.0,
          "feh_min":  0.0,    "feh_max":  0.0,
          "feh_fixed": true,
          "n_points": 116
        }
      ]
    }
  ]
}

Field semantics (per filter entry)

Field semantics (per model entry)

Notes for callers

• Filter codes are case-sensitive. In particular, lowercase letters distinguish Strömgren from uppercase Johnson: “V” is Johnson V; “v” is Strömgren v. SDSS codes use a trailing asterisk: u*, g*, r*, i*, z*.
• The complete current list of codes is: U, B, V, R, I, J, H, K, u, v, b, y, u*, g*, r*, i*, z*, Kp, C, S1, S2, S3, S4, TESS, CBB, CHEOPS.
• The model parameter to /api/compute accepts the display name from the model field. Accepted values are ‘ATLAS’, ‘PHOENIX’, and ‘PHOENIX-COND’. Not every filter supports every model; the models array per filter is the authoritative list.
• When the feh_fixed flag is true, passing a feh value other than 0.0 to /api/compute will be rejected. The default feh=0.0 works correctly.

6GET /api/resolve

Looks up an exoplanet name or TESS Object of Interest (TOI) candidate identifier and returns host-star stellar parameters from the authoritative source (NEA for confirmed planets; ExoFOP-TESS for TOI candidates not in NEA).

Required parameters

Optional parameters: none.

Examples of valid input

• WASP-23 b
• wasp-23 b  (case-insensitive)
• HD 189733 b
• TRAPPIST-1 e
• TOI-700.01
• TOI 700.01  (TOI prefix can use a space or hyphen)

Response when found (HTTP 200)

{
  "found": true,
  "planet": "WASP-23 b",
  "hostname": "WASP-23",
  "teff": 5150.0,
  "logg": 4.4,
  "feh":  -0.05,
  "source": "NEA",
  "citation": "DOI: 10.26133/NEA13"
}

Response when not found (HTTP 200, found=false)

{
  "found": false,
  "planet": "<input as supplied>",
  "reason": "not_in_nea",
  "suggestions": ["WASP-23 b", "WASP-3 b", "WASP-43 b"]
}

Response on upstream error (HTTP 200, found=false)

This is only returned in a degraded mode (the server cache is empty and a live upstream query also failed). In normal operation this shape is not returned.

{
  "found": false,
  "planet": "<input as supplied>",
  "reason": "error",
  "error": "NEA query timed out"
}

Field semantics

Citation strings returned

• For NEA lookups: ‘DOI: 10.26133/NEA13’
• For ExoFOP lookups: ‘ExoFOP-TESS, NExScI/Caltech-IPAC’

Notes for callers

• Any of teff, logg, or feh may be null even on a found=true response. This is faithful to the source — some NEA/ExoFOP entries genuinely lack values for individual parameters. Callers should handle null and either prompt the user to supply a value or skip the LDC computation.
• The source field tells the caller whether the values came from NEA’s curated composite parameters table or from ExoFOP’s TOI catalog. These pipelines can disagree by ~100 K on T_eff or ~0.1 dex on [Fe/H] for the same star. This is expected and not an error.
• Lookups are typically served from cache; expect sub-100 ms response.
• The HTTP status code is 200 even on found=false. The body’s found field is the success indicator. Callers should not branch on HTTP status alone for the resolve endpoint.
• Inputs that look like TOI identifiers (e.g., TOI-700, TOI-700 b, TOI-700.01) are handled in a flexible manner. The name format TOI-700 and TOI-700 b will query NEA first and, if not found, will query ExoFOP as a backup. The name format TOI-700.01 will query ExoFOP first. Callers do not need to implement this routing logic; just pass the user’s input string and inspect the source field of the response to know where the values came from.

7GET /api/compute

Computes quadratic limb-darkening coefficients (u₁, u₂) by trilinear interpolation of the Claret table corresponding to the requested filter and atmosphere model. This is the main computational endpoint.

Required parameters

Optional parameters

Response on success (HTTP 200)

{
  "u1": 0.5124,
  "u2": 0.1558,
  "filter_code": "i*",
  "filter_name": "SDSS i'",
  "model": "ATLAS",
  "citation": "Claret & Bloemen (2011, A&A 529, A75)",
  "grid": {
    "teff_bracket": [5000.0, 5250.0],
    "logg_bracket": [4.0, 4.5],
    "feh_bracket": [-0.5, 0.0],
    "fractions": { "teff": 0.4, "logg": 0.8, "feh": 0.9 },
    "on_grid": false
  }
}

(The numeric values above are illustrative; actual values from the live API may differ.)

Response on invalid input (HTTP 400)

{
  "detail": "Invalid Input (Teff = 1500.0 K): The PHOENIX model does not support values of Teff below 2000 K."
}

Field semantics

Citation strings by source

• CB2011 filters: ‘Claret & Bloemen (2011, A&A 529, A75)’
• C2018 (TESS only): ‘Claret (2018, A&A 618, A20)’
• C2021 (CHEOPS only): ‘Claret (2021, RNAAS 5, 13)’
• CMG2022 (CBB only): ‘Claret, Mullen & Gary (2022, RNAAS 6, 169)’

Notes for callers

• For PHOENIX models in CB2011, the [Fe/H] grid is degenerate (solar metallicity only). Passing feh=0.0 (the default) is correct; passing other values is rejected.
• For TESS in the C2018 table, the [Fe/H] grid is similarly degenerate.
• For CHEOPS in the C2021 table, ATLAS coefficients span all tabulated metallicities, while the PHOENIX-COND coefficients are at solar metallicity only.
• Inputs outside the grid range raise HTTP 400 with a human-readable detail message. The error message often includes a suggestion for an alternative model (e.g., ‘Use the PHOENIX model instead’ when an ATLAS request is below 3500 K).
• u₁ and u₂ are returned as full-precision IEEE 754 doubles. The Claret published values are themselves to 4 decimal places; sco-ldc does not artificially round the interpolation result.
• The grid block is informational. Callers that don’t need interpolation diagnostics can ignore it.

8Error responses

A summary of every error case the API can return:

Callers should treat any non-2xx response as a generic failure unless they specifically want to surface the message from detail.

9Implementation notes

Caching

Both the NEA planet table and the ExoFOP TOI table are cached in-memory on the server and refreshed once daily at 17:00 UTC. Callers do not need to invalidate or refetch on a faster cadence. Repeated /api/resolve calls for the same planet within a session will return identical values until the next daily refresh.

No rate limiting (currently)

The API has no enforced rate limits. The architecture handles dozens of requests per second comfortably. That said, individual workflows should not need more than a handful of calls per target, so this is not a real concern for normal use.

Network failures

If sco-ldc is unreachable (Render outage, DNS failure, network partition), the appropriate caller behavior is to surface this to the user and fall back to manual entry. The server should not be assumed to be always available.

Connection reuse

For occasional individual calls, connection management is a minor optimization. For higher-volume callers (a script processing many targets sequentially), it matters significantly: opening a fresh TLS connection per call adds 400–500 ms of handshake latency, while reusing an open connection eliminates this entirely. Most modern HTTP client libraries handle connection reuse via configured connection pools.

Recommended timeouts

Connection timeout 10 seconds, read timeout 30 seconds. Compute calls typically respond in 50–100 ms; resolve calls take a similar amount for cached planets and may take several seconds for live fallback queries when the cache misses. The 30-second read timeout gives ample headroom for slow network conditions without aborting on transient blips.

Filter discovery

Callers should ideally call /api/filters once per session (at startup, or lazily on first use) to discover the supported filters and grid ranges, rather than hardcoding the filter list. New filters may be added in future versions; calling /api/filters keeps the caller current automatically.

Citation surfacing

Each /api/resolve and /api/compute response includes a citation field. If a caller surfaces LDC values to a user, including the citation alongside (or in a tooltip) is the appropriate attribution and makes traceability straightforward. The two citations from a chained resolve+compute call are typically both needed for complete attribution in a publication.

10Example calls

Health check

GET https://sco-ldc.com/api/health
$ curl https://sco-ldc.com/api/health

Get filter catalog

GET https://sco-ldc.com/api/filters
$ curl https://sco-ldc.com/api/filters

Resolve a planet name

GET https://sco-ldc.com/api/resolve?planet=WASP-23+b
$ curl 'https://sco-ldc.com/api/resolve?planet=WASP-23%20b'

Resolve a TOI candidate

GET https://sco-ldc.com/api/resolve?planet=TOI-700.01

Compute LDCs

GET https://sco-ldc.com/api/compute?teff=5150&logg=4.4&feh=-0.05&filter=V&model=ATLAS
$ curl 'https://sco-ldc.com/api/compute?teff=5150&logg=4.4&feh=-0.05&filter=V&model=ATLAS'

Compute with default metallicity

GET https://sco-ldc.com/api/compute?teff=5150&logg=4.4&filter=V

Omitting feh defaults to 0.0; omitting model defaults to ATLAS.

Full target-to-LDC chain

To produce LDCs for WASP-23 b in Johnson V:

1. GET /api/resolve?planet=WASP-23+b returns teff, logg, feh values from NEA.
2. GET /api/compute?teff=<…>&logg=<…>&feh=<…>&filter=V&model=ATLAS returns u₁ and u₂.

The two-step chain is the canonical pattern for integrators (such as AstroImageJ) where the user supplies a planet name and the integration tool needs to populate LDCs automatically.

11Code

Source code repository: https://github.com/SCO-SCI/sco-ldc