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": { ... }
}
}| Field | Required | Description |
|---|---|---|
data | Yes | The response payload — shape varies by endpoint |
meta | No | Optional metadata object |
meta.warning | No | Non-fatal warning the caller should be aware of |
meta.pagination | No | Present 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:
| Warning | Meaning |
|---|---|
"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:
| Value | Meaning | Example |
|---|---|---|
merged | Combined from both on-chain and off-chain sources | A course with DB metadata and on-chain state |
chain_only | Exists on-chain but has no off-chain record | A course created by another API instance |
db_only | Exists in the database but not yet on-chain | A 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 stateGET /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| State | On-chain | DB synced | Safe to read? |
|---|---|---|---|
pending | No | No | No |
confirmed | Yes | No | No |
updated | Yes | Yes | Yes |
failed | Yes | No (retrying) | No — will auto-heal |
expired | No | No | Check 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:
status | Meaning |
|---|---|
ok | Prerequisites are configured; aliases is the set of fully-qualified contributors (may be empty if none qualify). |
no_prerequisites_configured | The 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
- Transaction Handling — The full transaction lifecycle
- Error Handling — Failure modes and recovery
- API Reference — Complete endpoint documentation