Atlas Operations
Query and optionally correct the Atlas Commerce Operations database through its HTTP API. The API provides schema introspection, a read-only SQL endpoint, a transactional SQL endpoint, and a correction-audit view.
Connectivity
The base URL is provided in the task prompt as <TASK_ENV_BASE_URL> (or an
equivalent placeholder). The authorization header from the environment access
notes must be sent on every request:
Authorization: Bearer atlas-ops-token-022
All endpoints expect JSON and return JSON.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/schema |
List all tables and columns |
| GET | /api/data-dictionary |
Human-readable descriptions of every column |
| POST | /api/sql |
Run a read-only analytical SELECT query |
| POST | /api/sql/transaction |
Run a controlled UPDATE (corrections only) |
| GET | /api/correction-audit |
Inspect committed correction audit records |
Workflow
Step 1 – Orient
Read the task prompt and the request payload (usually a JSON file under
input/payloads/). The payload defines the scope, business definitions,
rollup rules, classification policies, and rounding. Also read the
answer template (answer_template.json) — it is a strict JSON Schema
describing every required field and its constraints. The final answer
must conform to it with no extra fields.
Step 2 – Explore the schema
Fetch GET /api/schema and GET /api/data-dictionary. Use them to
understand table names, column names, column types, relationships, and
what each field means. See references/schema_exploration.md
for exploration patterns.
Step 3 – Build and run analytical queries
Translate the business definitions from the request payload into SQL.
POST each query body to /api/sql:
{"query": "SELECT ..."}
See references/sql_patterns.md for common query patterns (time windows, effective/canonical resolution, JOINs, aggregation, NULL handling).
Run one query at a time. Use results from earlier queries to refine later ones when needed.
Step 4 – Compute derived values
Process raw query results into the fields required by the answer template. See references/computation_patterns.md for rounding conventions, multi-level sorting with tiebreakers, tiered status classification, rate calculations, and median.
Step 5 – Corrections (only when the task requests one)
When the task payload includes an approved_correction block, the task
requires a controlled data mutation:
- Use
POST /api/sqlto find the exact row that needs correction. - Build an
UPDATEstatement that changes only the single canonical field identified in the correction scope.WHEREmust target the specific row by its stable identifier. - POST the UPDATE to
/api/sql/transaction:
Include every metadata field exactly as given in the request payload's{"query": "UPDATE ... SET ... WHERE ...", "audit_id": "...", "correction_key": "...", "reason_code": "...", "corrected_at": "...", "actor": "..."}approved_correctionblock. - The response reports
affected_business_rowsandaudit_rows. - Run a post-correction
SELECTvia/api/sqlto confirm the new value is in place. - Verify the audit record with
GET /api/correction-audit. - Report
APPLIEDonly when exactly one business row and one audit row committed AND the post-change query confirms the corrected value. Otherwise reportNOT_APPLIED.
Raw source values, source identity fields, and unrelated business rows must remain unchanged.
Step 6 – Write the answer
Write a single JSON object to answer.json that conforms exactly to
the answer template schema. No narrative text, no additional fields.
All array elements must be ordered as specified. All numeric fields
must respect the stated rounding and precision.
Key conventions
- Rounding: Apply rounding only to final reported values, using the precision stated in the request payload (typically 4 decimal places for rates, 2 for currency, 2 for hours). Keep intermediate values unrounded.
- Sorting: Follow the payload's ordering specification exactly. When a tiebreaker is "ascending by X", that applies only among items that tie on the primary sort key.
- Time windows: Inclusive boundaries on both ends unless the
payload states otherwise. Cutoffs are evaluated strictly (
<for "before",<=for "at or before"). - "Effective" / "canonical": Some tables have both raw and canonical columns. Business logic always uses the canonical or effective column, never the raw source column.
- NULL handling: An absent value changes semantics — e.g., an order with no shipment is incomplete, an incomplete order with no shipment promise does not satisfy the severe-exception time condition.