Andamio Logo
API/Guides

API Concepts

Response envelope, pagination, source field architecture, and safe refetch timing

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

Response Envelope

Every successful Andamio API response wraps its payload in a standard envelope:

{
  "data": { ... },
  "meta": {
    "warning": "optional warning message",
    "pagination": { ... }
  }
}
FieldRequiredDescription
dataYesThe response payload — shape varies by endpoint
metaNoOptional metadata object
meta.warningNoNon-fatal warning the caller should be aware of
meta.paginationNoPresent on paginated list endpoints

Pagination

List endpoints use one of two pagination formats depending on whether the list is a snapshot or an append-only feed.

Snapshot lists (courses, projects, commitments — data that can change between pages):

{
  "data": [ ... ],
  "meta": {
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 100
    }
  }
}

Cursor-based feeds (append-only data like audit logs):

{
  "data": [ ... ],
  "meta": {
    "pagination": {
      "next_cursor": 12345,
      "has_more": true
    }
  }
}

Cursor tokens are opaque — do not parse or construct them client-side. Pass the value of next_cursor directly as the cursor query parameter on the next request.

Warnings

meta.warning is a non-fatal signal that the response succeeded but data may be partial. It appears on merged endpoints when the API cannot read part of the data, either the off-chain content or the on-chain state. Each text names the data that is missing:

WarningMeaning
"Off-chain content not available"No off-chain content in the response
"Off-chain content not available, showing on-chain data only"The response holds on-chain data only
"Off-chain content not available, showing pending on-chain items only"The response holds pending on-chain items only
"Some off-chain content not available"Some records are missing their off-chain content
"Some off-chain commitment content not available"Some commitments are missing their off-chain content
"On-chain state not available"No on-chain state in the response
"On-chain state not available, showing off-chain content only"The response holds off-chain content only
"On-chain state not available, showing off-chain history only"The response holds off-chain history only
"On-chain status not available"Records are listed without their on-chain status
"Some on-chain data unavailable"Some records are missing their on-chain data
"On-chain learner status not available"The learner's on-chain status is missing
"Evidence not available, showing on-chain data only"Evidence is missing, and the response holds on-chain data only
"Commitment status not available for some assignments"Some assignment commitments are listed without a commitment_status

One response can carry more than one of these texts in a single meta.warning, joined by "; ". Split the field on "; " before you match, and do not exact-match the whole field.

When meta.warning is present, treat the response as degraded — display what you have but avoid taking actions that depend on the completeness of the data.

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:

ValueMeaningExample
mergedCombined from both on-chain and off-chain sourcesA course with DB metadata and on-chain state
chain_onlyExists on-chain but has no off-chain recordA course created by another API instance
db_onlyExists in the database but not yet on-chainA draft course not yet minted

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 a set of endpoints that combine DB and Andamioscan data into unified views. For example:

  • POST /v2/user/dashboard — Consolidated user dashboard (courses, projects, pending assessments)
  • GET /v2/course/user/courses/list — Courses with merged on-chain state
  • GET /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, always-current list.

Safe Refetch Timing

Only read data after updated, not confirmed.

The confirmed state means the transaction is on-chain, but the off-chain database has not synced yet. Reading at confirmed is an intermittent bug — it works on fast networks but breaks under load.

The transaction state machine has five states:

pending → confirmed → updated
                   ↘ failed
       ↘ expired
StateOn-chainDB syncedSafe to read?
pendingNoNoNo
confirmedYesNoNo
updatedYesYesYes
failedYesNo (retrying)No — will auto-heal
expiredNoNoCheck Andamioscan first

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>

Qualified Contributors

For a project with prerequisite credentials, a manager can ask which aliases currently hold every required credential — useful for gating who may be assigned tasks:

GET /v2/project/manager/contributors/get-qualified?project_id=<id>

The caller must be a manager of the project. The response includes a status field:

statusMeaning
okPrerequisites are configured; aliases is the set of fully-qualified contributors (may be empty if none qualify).
no_prerequisites_configuredThe project has no on-chain prerequisites; aliases is always empty.

The no_prerequisites_configured status lets you distinguish "no one qualifies yet" from "this project gates nothing" — they both return an empty list but mean very different things in your UI.

Next Steps