API Integration

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

Authentication Headers

All Andamio API requests require two authentication headers:

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 endpoints for:

Category	Base Path	Description
Auth	`/api/v2/auth/*`	Challenge/verify, JWT management
Courses	`/api/v2/course/*`	Course CRUD, modules, enrollments
Projects	`/api/v2/project/*`	Project CRUD, tasks, contributors
Transactions	`/api/v2/tx/*`	Build and register on-chain transactions
Global	`/api/v2/global/*`	Access tokens, platform config

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

Transaction Handling — Build, sign, and submit transactions
Error Handling — Recovery patterns for failed requests
Preprod API Docs — Full endpoint reference