Skip to main content

​
Core API Concepts

This section covers the fundamental concepts and design principles that underpin the Weir AI API v1.0.1. Understanding these concepts will help you build more effective and reliable integrations.

​
API Architecture Overview

The Weir AI API v1.0.1 follows a modern, RESTful architecture designed for scalability, security, and ease of use.

RESTful Design

All endpoints follow REST principles with clear resource-based URLs, standard HTTP methods, and consistent response formats.

Multi-Tenant Architecture

Support for multiple organizations, teams, and platforms with proper isolation and access control.

Role-Based Access Control

Different API categories (External, Console, Admin) with appropriate permissions and authentication methods.

Scalable Infrastructure

Built to handle high-volume requests with proper rate limiting and monitoring capabilities.

​
API Categories and Use Cases

The Weir AI API is organized into three main categories, each serving specific use cases:

​
External APIs

Purpose: Public-facing APIs for third-party integrations
  • Basic authentication with client credentials
  • Access token generation for external applications
  • Limited scope for public integrations
  • Third-party application integrations
  • Public API access for external developers
  • Limited functionality for security
  • Client credential-based authentication
  • 100 requests per minute per client
  • 10 token generation requests per minute
  • Burst limit of 200 requests per 5-minute window

​
Console APIs

Purpose: Organization management and internal operations
  • Team management and member invitations
  • Platform creation and management
  • Client and talent roster management
  • User profile and authentication management
  • Subscription and billing management
  • Internal management tools
  • Organization administration
  • Team collaboration platforms
  • Platform management interfaces
  • User management systems
  • 200 requests per minute per user
  • 5 login requests per minute per IP
  • Burst limit of 500 requests per 5-minute window

​
Admin APIs

Purpose: Platform administration and system management
  • Administrative user management
  • System-wide platform and organization management
  • Pod management and system control
  • Mail template management
  • Comprehensive logging and monitoring
  • System administration dashboards
  • Platform monitoring and management
  • User administration tools
  • System maintenance and operations
  • Audit and compliance tools
  • 500 requests per minute per admin
  • 10 admin login requests per minute per IP
  • Burst limit of 1000 requests per 5-minute window

​
Authentication and Security

​
Authentication Methods

Basic Authentication

Used for External APIs with client credentials to generate access tokens.

Bearer Token

Used for authenticated requests with access tokens across all API categories.

Session-based

Used for Console and Admin APIs with username/password authentication.

​
Security Features

  • JWT-based access tokens with 1-hour expiration
  • Refresh tokens with 30-day expiration
  • Automatic token refresh capabilities
  • Secure token storage recommendations
  • Category-specific rate limits
  • Burst protection with sliding windows
  • Rate limit headers in responses
  • Exponential backoff recommendations
  • Comprehensive parameter validation
  • SQL injection prevention
  • XSS protection
  • CSRF protection for web applications

​
Data Models and Relationships

​
Core Entities

Purpose: Top-level entities representing companies or institutionsProperties:
  • Unique organization ID
  • Organization name and details
  • Subscription and billing information
  • Contact information and settings
Relationships:
  • Contains multiple teams
  • Owns multiple platforms
  • Has multiple users
  • Manages multiple clients
Purpose: Groups of users within an organizationProperties:
  • Unique team ID
  • Team name and description
  • Creation timestamp
  • Member count and status
Relationships:
  • Belongs to an organization
  • Contains multiple members
  • Associated with platforms
  • Has role-based permissions
Purpose: Individual users within the systemProperties:
  • Unique user ID
  • Personal information (name, email)
  • Authentication credentials
  • Role and permissions
Relationships:
  • Belongs to an organization
  • Member of multiple teams
  • Has specific roles and permissions
  • Associated with user profile
Purpose: Applications or services within an organizationProperties:
  • Unique platform ID
  • Platform name and type
  • Domain and verification status
  • Team association
Relationships:
  • Belongs to an organization
  • Associated with a team
  • Has multiple clients
  • Contains talent rosters
Purpose: API clients for platformsProperties:
  • Unique client ID
  • Client name and environment
  • API credentials
  • Creation and refresh timestamps
Relationships:
  • Belongs to a platform
  • Has API credentials
  • Associated with environment (production/staging)

​
Data Flow

Organization Setup

Organizations are created with basic information and subscription details.

Team Creation

Teams are created within organizations to group users and manage permissions.

User Management

Users are invited to teams with specific roles and permissions.

Platform Development

Platforms are created and associated with teams for development and management.

Client Configuration

API clients are created for platforms to enable external integrations.

​
Error Handling and Response Formats

​
Standard Response Format

All API responses follow a consistent format: 
{
  "data": {
    // Response data object
  },
  "message": "Human-readable message",
  "status": "success|error"
}

​
Error Response Format

Error responses include detailed information: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details or validation errors"
  },
  "status": "error"
}

​
HTTP Status Codes

Success Codes

  • 200 OK: Successful GET, PUT, PATCH requests
  • 201 Created: Successful POST requests
  • 204 No Content: Successful DELETE requests

Error Codes

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error

​
Rate Limiting and Throttling

​
Rate Limit Headers

All API responses include rate limiting information:
​
X-RateLimit-Limit
string
Maximum number of requests allowed per time window.
​
X-RateLimit-Remaining
string
Number of requests remaining in the current time window.
​
X-RateLimit-Reset
string
Unix timestamp when the rate limit window resets.

​
Rate Limit Strategies

Implement exponential backoff with jitter when rate limits are hit:
const delay = Math.min(1000 * Math.pow(2, retryCount), 30000);
const jitter = Math.random() * 1000;
await new Promise(resolve => setTimeout(resolve, delay + jitter));
Queue requests to stay within rate limits:
class RateLimitedQueue {
  constructor(requestsPerMinute) {
    this.queue = [];
    this.interval = 60000 / requestsPerMinute;
    this.processQueue();
  }
  
  async add(request) {
    return new Promise((resolve) => {
      this.queue.push({ request, resolve });
    });
  }
}
Cache responses to reduce API calls:
const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedData(key, fetchFunction) {
  const cached = cache.get(key);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await fetchFunction();
  cache.set(key, { data, timestamp: Date.now() });
  return data;
}

​
Best Practices

​
API Integration

  • Store credentials securely in environment variables
  • Implement automatic token refresh
  • Handle authentication errors gracefully
  • Use different credentials for different environments
  • Implement comprehensive error handling
  • Provide clear error messages to users
  • Log errors for debugging
  • Handle network failures gracefully
  • Cache responses when possible
  • Use pagination for large datasets
  • Implement retry logic with backoff
  • Monitor rate limit headers
  • Always use HTTPS
  • Validate and sanitize input
  • Implement proper CORS policies
  • Follow OWASP security guidelines

​
Development Workflow

Environment Setup

Set up development, staging, and production environments with appropriate API credentials.

API Testing

Use the API playground and testing tools to verify endpoint functionality.

Integration Development

Develop your integration following best practices and error handling patterns.

Testing and Validation

Test your integration thoroughly with various scenarios and edge cases.

Deployment and Monitoring

Deploy to production and monitor API usage, performance, and errors.

​
Versioning and Compatibility

​
API Versioning

The Weir AI API uses URL-based versioning:
  • Current Version: v1.0.1
  • Version Format: /v{major}.{minor}.{patch}
  • Backward Compatibility: Minor and patch versions maintain backward compatibility
  • Breaking Changes: Only major version changes introduce breaking changes

​
Migration Guidelines

  • Review changelog for new features and changes
  • Test new endpoints in staging environment
  • Update client code to handle new response formats
  • Monitor for deprecated endpoints and plan migration
  • Major version updates may introduce breaking changes
  • Review migration guides for detailed instructions
  • Plan migration timeline and testing strategy
  • Update documentation and client code accordingly
Pro Tip: Start with the External APIs for simple integrations, use Console APIs for organization management, and only use Admin APIs for system administration tasks.