API Reference
Endpoints

API Endpoints

The NIL Taxonomy API provides RESTful endpoints for accessing taxonomy data.

Base URL: https://api.nil-taxonomy.org/api/nil

Authentication

All endpoints except /health require authentication via API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.nil-taxonomy.org/api/nil/v1/licenses

Get an API key →

Endpoints

GET /health

Health check endpoint (no authentication required)

curl https://api.nil-taxonomy.org/api/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-27T10:30:00Z"
}

GET /v1/licenses

Get all base license templates

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.nil-taxonomy.org/api/nil/v1/licenses

Response:

{
  "version": "v1.0",
  "licenses": [
    {
      "code": "NIL-EDU",
      "name": "Educational License",
      "description": "For documentaries, news, classroom use",
      "config": {
        "subject_scope": ["name", "image", "likeness"],
        "use_type": ["editorial", "educational"],
        "commercial_scope": "non_commercial",
        ...
      }
    },
    ...
  ],
  "count": 4
}

SDK equivalent:

const licenses = await client.getBaseLicenses('v1');

GET /v1/licenses/:code

Get a specific base license by code

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.nil-taxonomy.org/api/nil/v1/licenses/NIL-EDU

Response:

{
  "code": "NIL-EDU",
  "name": "Educational License",
  "description": "For documentaries, news, classroom use",
  "config": { ... },
  "version": "v1.0",
  "published_at": "2024-11-20T00:00:00Z"
}

SDK equivalent:

const license = await client.getBaseLicense('NIL-EDU', 'v1');

GET /v1/dimensions

Get all taxonomy dimensions

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.nil-taxonomy.org/api/nil/v1/dimensions

Response:

{
  "version": "v1.0",
  "dimensions": {
    "subject_scope": {
      "name": "Subject Scope",
      "description": "What aspects of the athlete are covered",
      "values": ["name", "image", "likeness", "signature_marks", ...]
    },
    "use_type": { ... },
    ...
  },
  "count": 12
}

SDK equivalent:

const dimensions = await client.getDimensions('v1');

GET /v1/schema

Get complete taxonomy schema

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.nil-taxonomy.org/api/nil/v1/schema

Response:

{
  "version": "v1.0",
  "namespace": "NILv1",
  "published_at": "2024-11-20T00:00:00Z",
  "dimensions": { ... },
  "base_licenses": [ ... ],
  "validation_rules": { ... }
}

SDK equivalent:

const schema = await client.getSchema('v1');

Response Format

All successful responses include:

{
  "version": "v1.0",      // Taxonomy version
  "data": { ... },        // Requested data
  "_meta": {              // Metadata
    "timestamp": "2024-01-27T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Taxonomy-Version: v1.0
X-API-Version: v1
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
X-Request-ID: req_abc123

Rate Limiting

API usage is limited based on tier:

TierRequests/HourRequests/Day
Free1001,000
Professional1,00010,000
EnterpriseUnlimitedUnlimited

Rate Limit Headers

X-RateLimit-Limit: 100           # Your hourly limit
X-RateLimit-Remaining: 95        # Requests remaining
X-RateLimit-Reset: 1640995200    # Unix timestamp when limit resets

Rate Limit Exceeded

When you exceed your limit:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
 
{
  "error": "Rate limit exceeded",
  "message": "Limit of 100 requests per hour exceeded",
  "retry_after": 3600,
  "upgrade_url": "https://nil-taxonomy.org/pricing"
}

Caching

Cache-Control Headers

Taxonomy data is cacheable:

Cache-Control: public, max-age=3600, s-maxage=7200
ETag: "abc123"

Recommended Caching Strategy

// Cache for 1 hour
const cache = new Map();
const CACHE_TTL = 3600000; // 1 hour in ms
 
async function getCachedLicenses() {
  const cached = cache.get('licenses');
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await client.getBaseLicenses('v1');
  cache.set('licenses', { data, timestamp: Date.now() });
  
  return data;
}

Error Responses

See Error Codes for complete reference.

Common errors:

// 401 Unauthorized
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
 
// 404 Not Found
{
  "error": "Not Found",
  "message": "Base license 'INVALID-CODE' not found"
}
 
// 429 Too Many Requests
{
  "error": "Rate limit exceeded",
  "retry_after": 3600
}

CORS

The API allows cross-origin requests from any origin:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Authorization, Content-Type
⚠️

API keys should never be exposed in client-side code. Use a backend proxy for browser requests.

Webhooks (Future)

Webhook support is planned for v1.1. Subscribe to updates:

  • New version releases
  • Deprecation notices
  • Base license updates

Next Steps

TroubleshootingAuthentication