API Concepts

Core concepts for working with the Andamio API beyond basic request/response patterns.

The Source Field

Andamio stores data in two places: on-chain (Cardano blockchain, via Andamioscan) and off-chain (database, via DB API). Many API responses include a source field that tells you where the data came from:

Why This Matters

The Andamio protocol is a shared commons — anyone can create courses and projects on-chain. Your API instance only knows about off-chain records it created. When the gateway merges data from both sources, it labels each record so you know its provenance.

const courses = await fetch(`${API}/course/user/courses/list`, { headers });
const data = await courses.json();

for (const course of data) {
  switch (course.source) {
    case "merged":
      // Full data available — both metadata and on-chain state
      break;
    case "chain_only":
      // On-chain only — no local metadata, no module content
      // Display what's available, link to on-chain explorer
      break;
    case "db_only":
      // Draft — not yet on-chain, cannot be enrolled in
      break;
  }
}

Merged Endpoints

The gateway provides 27 endpoints that combine DB and Andamioscan data into unified views. These include:

• POST /v2/user/dashboard — Consolidated user dashboard (courses, projects, pending assessments)
• GET /v2/course/user/courses/list — Courses with merged on-chain state
• POST /v2/project/user/projects/list — Projects with merged on-chain state
• Role-specific views for owners, teachers, students, managers, and contributors

See the API Reference for the complete list.

Safe Refetch Timing

The transaction state machine has five states:

pending → confirmed → updated
                   ↘ failed
       ↘ expired

Why confirmed Is Unsafe

When a teacher assesses assignments while a student's enrollment transaction is confirmed but not yet updated, the DB still shows the old state. The teacher sees stale data and may take action on incorrect information.

Wait for updated before:

• Displaying transaction results to users
• Taking follow-up actions that depend on the new state
• Reading data that the transaction modified

You can safely read unrelated data at any time — only data affected by the in-flight transaction requires waiting for updated.

Monitoring State Changes

Use SSE for real-time updates:

const events = new EventSource(
  `${API}/tx/stream/${txHash}?api_key=${API_KEY}`
);

events.addEventListener("complete", (e) => {
  const { final_state } = JSON.parse(e.data);
  if (final_state === "updated") {
    // Safe to refetch and display
  }
});

Or poll with the CLI:

andamio tx status <tx-hash>

Event Queries

After a transaction confirms, you can parse exactly what happened using event query endpoints:

GET /v2/events/{type}/{action}/{tx_hash}

These endpoints extract structured data from on-chain transactions:

These are useful for building activity feeds, audit logs, or debugging transaction contents.

Next Steps

• Transaction Handling — The full transaction lifecycle
• Error Handling — Failure modes and recovery
• API Reference — Complete endpoint documentation