API Integration

API Reference: API Docs for endpoint schemas.

Authentication Headers

Most Andamio API requests require two authentication headers. Public endpoints (developer registration, billing plans, health checks) have reduced or no auth requirements.

const headers = {
  "Content-Type": "application/json",
  "X-API-Key": APP_API_KEY,
  "Authorization": `Bearer ${userJwt}`,
};

Making Requests

Once authenticated, include both headers in all requests:

// Example: List user's courses
const res = await fetch(`${API}/course/owner/courses/list`, {
  method: "GET",
  headers,
});
const courses = await res.json();

API Endpoints

The Andamio Gateway provides approximately 120 endpoints across these categories:

For the complete endpoint reference with request/response schemas, see the API Docs.

For transaction building and submission, see Transaction Handling.

Environment URLs

Start on preprod — it uses test ADA.

All code examples in these docs use preprod URLs.

Ready for Mainnet?

When your app is tested and ready for production:

1. Generate a mainnet API key at app.andamio.io/api-setup — the same portal that manages your preprod keys
2. Update your environment variables:

   NEXT_PUBLIC_ANDAMIO_GATEWAY_URL="https://api.andamio.io"
   NEXT_PUBLIC_CARDANO_NETWORK="mainnet"

3. Update the Access Token policy ID (contact team for mainnet ID)

See Environment Reference for full configuration details.

Error Responses

The Andamio API uses two error shapes depending on the endpoint. Both are in active use.

Legacy shape

Used by auth, transaction, billing, and most existing endpoints:

{
  "status_code": 401,
  "message": "Unauthorized: Invalid or missing credentials.",
  "details": "optional debug info"
}

Error envelope shape

Used by merged data endpoints (/v2/course/*/merged, /v2/project/*/merged, module, lesson, SLT endpoints):

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assignment not found",
    "details": "optional debug info"
  }
}

HTTP status to error code mapping

A 429 from your tier's rate limits or request quota does not use this envelope. See Quota Headers.

See Error Handling for recovery patterns.

Quota Headers

This section covers the Andamio API, called with a developer key. Each request that counts against your developer quota returns what is left in its response headers:

No header reports the per-second or per-minute limits.

When you exceed a limit, the API returns 429 Too Many Requests. A 429 carries none of these headers, and its body is { "error": "<message>" } rather than the error envelope. The message names the limit you hit: per second, per minute, daily or monthly. After a per-second or per-minute 429, back off and retry within the minute. After a daily or monthly 429, wait until the reset time from your last successful response.

Andamio Issuer keeps its own quota and returns 402 QUOTA_EXHAUSTED when it runs out. See Andamio Issuer API integration.

Your billing tier sets the limits. See Billing for the limits per plan.

Issuer Route Auth

Some endpoints under /api/v2/auth/issuer/* operate with stricter auth requirements than standard v2 routes. These routes reject requests that supply both X-API-Key and Authorization — sending both returns 400 Bad Request. Supply only the credential the endpoint requires.

For all other /api/v2/* routes, both headers are accepted together (the standard pattern above).

Next Steps

• API Concepts — Source field, safe refetch timing, event queries
• Transaction Handling — Build, sign, and submit transactions
• Error Handling — Recovery patterns and failure modes
• API Docs — Full endpoint reference