Andamio LogoAndamio
APIs

YAML Data API

Access Andamio protocol YAML files via REST API endpoints

YAML Data API

The Andamio documentation site provides comprehensive REST API endpoints to access all YAML protocol data for external applications.

Base URL

All API endpoints are available at: https://docs.andamio.io/api/

Available Endpoints

Registry API

Access the validator registry data:

  • GET /api/registry - Complete validator registry
  • GET /api/registry/systems/{system} - System-specific data

Transactions API

Access transaction definitions with optional deployment resolution:

  • GET /api/transactions - List all transactions
  • GET /api/transactions?role={role} - Filter by role
  • GET /api/transactions/{role}/{transaction} - Specific transaction
  • GET /api/transaction?file={file} - Transaction by file path
  • GET /api/expected-tx/{role}/{transaction} - Enhanced transaction data with resolved inputs/outputs
  • GET /api/expected-tx?file={file} - Enhanced transaction data by file path

Query Parameters for Transaction Endpoints

All transaction endpoints (/api/transactions/{role}/{transaction}, /api/transaction, /api/expected-tx/{role}/{transaction}, and /api/expected-tx) support:

  • deployment (optional) - Deployment name (default: "preprod")
  • version (optional) - Deployment version (default: "v1")

When these parameters are provided, the API will resolve addresses and policy IDs from the deployment files.

Expected Transaction Endpoint

The /api/expected-tx endpoints provide enhanced transaction data with resolved tokens and addresses. They accept the same parameters as the regular transaction endpoints but return structured data with:

  • Resolved blockchain addresses from deployment parameters
  • Policy IDs and asset names parsed from token definitions
  • Documentation links for each token
  • Properly formatted asset information

The endpoint can be accessed in two ways:

  1. By role and transaction: /api/expected-tx/{role}/{transaction}
  2. By file path: /api/expected-tx?file={role}/{transaction}.yaml

Deployments API

Access deployment parameters:

  • GET /api/deployments - List available deployments
  • GET /api/deployments/{deployment} - Deployment-specific data

File Discovery

  • GET /api/yaml - List all available YAML files

TypeScript Types

  • GET /api/types - Download TypeScript definitions file

Direct File Access

YAML files are also directly accessible with proper CORS headers:

  • GET /yaml/validator-registry-v1.yaml - Registry file
  • GET /yaml/transactions/{role}/{transaction}.yaml - Transaction files
  • GET /yaml/deployments/{deployment}/{file}.yaml - Deployment files

TypeScript Support

Complete TypeScript definitions are available for all API responses:

Installation Options

Option 1: Direct Download

# Download via API endpoint
curl -o andamio-api.d.ts https://docs.andamio.io/api/types

# Or download static file
curl -o andamio-api.d.ts https://docs.andamio.io/types/andamio-api.d.ts

Option 2: Copy from Documentation Copy the complete type definitions from this page into your project.

Option 3: Future NPM Package (Coming Soon)

# Will be available as:
npm install @andamio/api-types

Import Types

import type { 
  RegistryResponse,
  TransactionResponse,
  ResolvedTransactionResponse,
  ExpectedTxResponse,
  TransactionsListResponse,
  DeploymentsListResponse,
  ApiError
} from './andamio-api';

Response Types

Registry API

interface RegistryResponse {
  systems: {
    [key: string]: {
      validators?: { [key: string]: ValidatorInfo };
      tokens?: { [key: string]: TokenInfo };
    };
  };
}

interface SystemResponse {
  system: string;
  data: {
    validators?: { [key: string]: ValidatorInfo };
    tokens?: { [key: string]: TokenInfo };
  };
}

Transactions API

interface TransactionsListResponse {
  count: number;
  transactions: TransactionListItem[];
}

interface TransactionResponse {
  role: string;
  transaction: string;
  file: string;
  data: TransactionYaml;
}

// Enhanced response with deployment resolution
interface ResolvedTransactionResponse extends TransactionResponse {
  resolved?: {
    addresses: {
      [path: string]: string | null;
    };
    tokens: {
      [path: string]: string | null;
    };
  };
}

// Expected transaction response with resolved inputs/outputs
interface ExpectedTxResponse {
  label: string;
  linkUrl: string;
  docsId: string;
  inputs: ExpectedTxInput[];
  outputs: ExpectedTxOutput[];
}

interface ExpectedTxInput {
  address: string;
  docsId: string;
  assets: ExpectedTxAsset[];
}

interface ExpectedTxOutput {
  address: string;
  docsId: string;
  assets: ExpectedTxAsset[];
}

interface ExpectedTxAsset {
  label: string;
  linkUrl: string;
  docsId: string;
  policyId: string | undefined | null;
  assetName: string | undefined | null;
  quantity: string | undefined | null;
}

Deployments API

interface DeploymentsListResponse {
  count: number;
  deployments: DeploymentListItem[];
}

interface DeploymentResponse {
  deployment: string;
  files: {
    [fileName: string]: unknown | { error: string };
  };
}

Error Responses

interface ApiError {
  error: string;
  status: number;
}

Usage Examples

Transaction with Deployment Resolution

The transaction endpoints can resolve actual blockchain addresses and policy IDs from deployment files:

// Get transaction with mainnet deployment resolution
const response = await fetch(
  'https://docs.andamio.io/api/transactions/general/access-token-mint?deployment=mainnet&version=v1'
);
const txData: ResolvedTransactionResponse = await response.json();

// Access original transaction data
console.log(txData.data.inputs[0].output.address); // "user"

// Access resolved addresses
console.log(txData.resolved.addresses['inputs[1].output.address']); 
// "addr1x8nkqvydps2qjml508k97fy4g42stl4hjpgrjql7jakyl55ch6g0j0xe5272m2ysjs698fnmdlrpt4qseng6wp04z6ps..."

// Access resolved tokens with policy IDs
console.log(txData.resolved.tokens['outputs[0].output.value[0]']);
// "1 e760308d0c14096ff479ec5f2495455505feb790503903fe976c4fd2.222<alias>"

Using Different Deployments

// Preprod deployment (default)
const preprodTx = await fetch(
  'https://docs.andamio.io/api/transaction?file=admin/init-course.yaml'
).then(res => res.json());

// Mainnet deployment
const mainnetTx = await fetch(
  'https://docs.andamio.io/api/transaction?file=admin/init-course.yaml&deployment=mainnet&version=v1'
).then(res => res.json());

// Check if addresses were resolved
if (mainnetTx.resolved && Object.keys(mainnetTx.resolved.addresses).length > 0) {
  console.log('Addresses resolved from mainnet deployment');
}

Using Expected Transaction Endpoint

// Get enhanced transaction data with resolved addresses and tokens
// Option 1: Using role and transaction in URL
const expectedTx1: ExpectedTxResponse = await fetch(
  'https://docs.andamio.io/api/expected-tx/admin/init-course?deployment=preprod&version=v1'
).then(res => res.json());

// Option 2: Using file parameter
const expectedTx2: ExpectedTxResponse = await fetch(
  'https://docs.andamio.io/api/expected-tx?file=admin/init-course.yaml&deployment=preprod&version=v1'
).then(res => res.json());

// Access structured inputs with resolved data
expectedTx1.inputs.forEach(input => {
  console.log(`Input address: ${input.address}`); // Resolved blockchain address
  
  input.assets.forEach(asset => {
    console.log(`Asset: ${asset.label}`);
    console.log(`Policy ID: ${asset.policyId}`); // Resolved from deployment
    console.log(`Asset Name: ${asset.assetName}`); // Parsed from registry
    console.log(`Docs Link: ${asset.linkUrl}`); // Direct link to token docs
  });
});

// Access transaction documentation link
console.log(`Transaction docs: ${expectedTx1.linkUrl}`);
import type { 
  RegistryResponse, 
  TransactionResponse,
  ResolvedTransactionResponse, 
  TransactionsListResponse,
  ApiError 
} from './andamio-api';

// Fetch complete registry with type safety
const registry: RegistryResponse = await fetch('https://docs.andamio.io/api/registry')
  .then(res => res.json());

// Access typed data
const globalStateValidators = registry.systems['global-state']?.validators;
console.log(globalStateValidators?.['global-state']?.name); // "Global State"

// Get specific transaction with error handling
async function getTransaction(role: string, transaction: string): Promise<TransactionResponse> {
  const response = await fetch(
    `https://docs.andamio.io/api/transactions/${role}/${transaction}`
  );
  
  if (!response.ok) {
    const error: ApiError = await response.json();
    throw new Error(error.error);
  }
  
  return response.json();
}

// List all transactions for a role
const adminTxs: TransactionsListResponse = await fetch(
  'https://docs.andamio.io/api/transactions?role=admin'
).then(res => res.json());

// Process transaction list with type safety
adminTxs.transactions.forEach(tx => {
  console.log(`${tx.role}/${tx.transaction}: ${tx.url}`);
});

JavaScript

// Fetch complete registry
const registry = await fetch('https://docs.andamio.io/api/registry')
  .then(res => res.json());

// Get specific transaction
const transaction = await fetch(
  'https://docs.andamio.io/api/transactions/admin/add-course-creators'
).then(res => res.json());

// List all transactions for a role
const adminTxs = await fetch(
  'https://docs.andamio.io/api/transactions?role=admin'
).then(res => res.json());

Python

import requests

# Fetch registry
response = requests.get('https://docs.andamio.io/api/registry')
registry = response.json()

# Get deployment params
response = requests.get('https://docs.andamio.io/api/deployments/mainnet-v1')
deployment = response.json()

curl

# Get registry
curl https://docs.andamio.io/api/registry

# Get specific transaction
curl https://docs.andamio.io/api/transactions/contributor/mint-project-state

# Get transaction with mainnet deployment resolution
curl "https://docs.andamio.io/api/transactions/general/access-token-mint?deployment=mainnet&version=v1"

# Get expected transaction with resolved data (by role/transaction)
curl "https://docs.andamio.io/api/expected-tx/admin/init-course?deployment=preprod&version=v1"

# Get expected transaction with resolved data (by file)
curl "https://docs.andamio.io/api/expected-tx?file=admin/init-course.yaml&deployment=preprod&version=v1"

# List all available files
curl https://docs.andamio.io/api/yaml

# Download TypeScript definitions
curl -o andamio-api.d.ts https://docs.andamio.io/api/types

Direct YAML Access

# Download registry YAML directly
curl https://docs.andamio.io/yaml/validator-registry-v1.yaml

# Download transaction YAML
curl https://docs.andamio.io/yaml/transactions/admin/init-course.yaml

Rate Limits

  • No authentication required
  • Reasonable usage limits apply
  • Responses are cached for 5 minutes

CORS Support

All endpoints include proper CORS headers for authorized domains:

  • Allowed Origins:
    • http://localhost:3000 (development)
    • http://localhost:3001 (development)
    • https://app.andamio.io (production)
    • https://preprod.andamio.io (staging)
  • Access-Control-Allow-Methods: GET, OPTIONS
  • Access-Control-Allow-Headers: Content-Type

Error Handling

Standard HTTP status codes:

  • 200 - Success
  • 404 - Resource not found
  • 500 - Server error

Error responses include descriptive messages:

{
  "error": "Transaction 'invalid/transaction' not found",
  "status": 404
}

TypeScript Types Reference

Complete TypeScript definitions for Andamio YAML API responses

Andamio Transactions

Andamio Transactions