API Reference

/conjunctions API

Perform collision risk detection between satellites. Identify close approaches and calculate collision probabilities using multi-stage screening algorithms.

Analysis Pipeline

Input

Primary NORAD ID, threshold, look-ahead window

Coarse Screen

10-min propagation steps, eliminate 99% non-threats

Fine Screen

1-min steps, refine TCA to precise time

Probability

Foster's 2D method, Monte Carlo validation

POST/conjunctions/analyze

Performs conjunction analysis using current satellite positions. Fast analysis, no TLE propagation required.

Request

curl -X POST https://api.cryptik.tech/conjunctions/analyze \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"primary_norad_id": 25544, "look_ahead_hours": 24, "threshold_km": 10.0}'

Field	Type	Description
`primary_norad_id`	int	NORAD Catalog ID (required)
`look_ahead_hours`	int	Hours to look ahead (default: 24)
`threshold_km`	float	Distance threshold km (default: 10)

Response

{
  "primary_norad_id": 25544,
  "analyzed_at": "2025-02-13T14:30:00Z",
  "total_candidates": 3,
  "events": [{ "id": 1, "primary_norad_id": 25544, "secondary_norad_id": 44713, "tca": "...", "miss_distance_m": 523.4, "risk_level": "high" }]
}

Error Responses

400Invalid request body

404Primary satellite not found

500Analysis failed

POST/conjunctions/analyze/full

Full conjunction analysis with SGP4 propagation and probability calculation. Requires TLE data for accurate long-term predictions.

Request

curl -X POST https://api.cryptik.tech/conjunctions/analyze/full \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"primary_norad_id": 25544, "look_ahead_hours": 72, "threshold_km": 10.0}'

Field	Type	Description
`primary_norad_id`	int	NORAD Catalog ID (required)
`look_ahead_hours`	int	Hours to look ahead (default: 24)
`threshold_km`	float	Distance threshold km (default: 10)

Error Responses

400Invalid request body

404Primary satellite not found

503TLE repository not configured

500Analysis failed

GET/conjunctions

Retrieve stored conjunction events from the database.

Query Parameters

Parameter	Type	Description
`risk_level`	string	Filter: low, medium, high, critical
`limit`	int	Max results (default: 100)

Response

{
  "conjunctions": [{ "id": 1, "primary_norad_id": 25544, "secondary_norad_id": 44713, "tca": "...", "miss_distance_m": 523.4, "risk_level": "high" }],
  "total": 1
}

Example

# Get all conjunctions
curl -X GET https://api.cryptik.tech/conjunctions -H "Authorization: Bearer <token>"

# Get high-risk only
curl -X GET "https://api.cryptik.tech/conjunctions?risk_level=high" -H "Authorization: Bearer <token>"

Risk Level Classification

critical

Miss distance < 100m OR probability > 1e-4

high

Miss distance < 500m OR probability > 1e-5

medium

Miss distance < 1000m OR probability > 1e-6

low

Miss distance ≥ 1000m AND probability ≤ 1e-6

Algorithms

Coarse Screening

Eliminates >99% of non-threatening objects using geometric approximations.

Propagate both satellites on coarse time grid (10-min steps)
Calculate minimum distance over look-ahead window
If distance < threshold, add to candidates for fine screening

Fine Screening

Refines Time of Closest Approach (TCA) with 1-minute steps.

Define refinement window around coarse TCA (±30 minutes)
Propagate with 1-minute steps to find precise TCA
Calculate relative state at TCA

Probability Calculation (Foster's 2D Method)

Pc = exp(-0.5 * h²) * (1 - exp(-0.5 * r²)) * erfc(u / (√2 * r))

Where:
  h = cross-track miss, u = along-track miss, r = hard sphere radius