API Integration

API Reference: Preprod API Docs for endpoint schemas. For production, use mainnet.api.andamio.io.

Authentication Headers

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

Header	Purpose	How to get
`X-API-Key`	Application-level (your app)	Getting Started
`Authorization: Bearer <jwt>`	User-level (wallet signature)	Authentication

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:

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

// 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:

Category	Base Path	Description	Guide
User Auth	`/api/v2/auth/login/*`	Wallet challenge/verify, User JWT	Authentication
Developer Auth	`/api/v2/auth/developer/*`	Registration, email verification, Developer JWT	Developer Accounts
API Keys	`/api/v2/apikey/*`	Key request, rotation, profile, usage	API Keys
Billing	`/api/v2/billing/*`	Plans, checkout, subscription management	Billing
Verification	`/api/v2/verify/*`	Access token ownership proof	Verification
Courses	`/api/v2/course/*`	Course CRUD, modules, enrollments, merged views
Projects	`/api/v2/project/*`	Project CRUD, tasks, contributors, merged views
Transactions	`/api/v2/tx/*`	Build, register, status, SSE stream (17 build endpoints)	Transactions
Users	`/api/v2/users/*`	User state, owned/enrolled/completed resources
Events	`/api/v2/events/*`	Parse what happened in a confirmed transaction	API Concepts
Token Registry	`/api/v2/token/*`	Native asset registration and listing
Dashboard	`/api/v2/user/dashboard`	Consolidated user view (courses + projects)

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

For transaction building and submission, see Transaction Handling.

Environment URLs

Start on preprod — it uses test ADA.

Environment	Gateway URL	App URL	Network
Preprod (start here)	`preprod.api.andamio.io`	preprod.app.andamio.io	Cardano Preprod
Production	`mainnet.api.andamio.io`	app.andamio.io	Cardano Mainnet

All code examples in these docs use preprod URLs.

Ready for Mainnet?

When your app is tested and ready for production:

Generate a mainnet API key at app.andamio.io/api-setup

Update your environment variables:

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

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

See Environment Reference for full configuration details.

Error Responses

API errors return JSON with error and message fields:

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or expired JWT"
}

Common error codes:

Code	Meaning
`UNAUTHORIZED`	Missing or invalid auth headers
`FORBIDDEN`	User lacks permission for this action
`NOT_FOUND`	Resource doesn't exist
`VALIDATION_ERROR`	Invalid request body
`TX_BUILD_FAILED`	Transaction building failed

See Error Handling for recovery patterns.

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
Preprod API Docs — Full endpoint reference