API Reference

Complete API documentation for Staque IO endpoints. All authenticated endpoints require a valid JWT token in the Authorization header.

Base URL

http://localhost:3000  # Development
https://your-domain.com  # Production

Authentication

Include the JWT token in the Authorization header for all protected endpoints:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Categories

Authentication APIs

Login, logout, and token validation endpoints

POST /api/auth/login
POST /api/auth/logout
GET /api/auth/validate

Model APIs

List and query available AI models

GET /api/models/bedrock
GET /api/models/sagemaker
GET /api/models/nvidia

Deployment APIs

Deploy models to various platforms

POST /api/deploy/bedrock
POST /api/deploy/sagemaker
POST /api/deploy/nims

Chat APIs

Interact with deployed models

POST /api/chat
POST /api/chat/thread
GET /api/chat/thread

Resource APIs

Monitor and control deployed resources

GET /api/resources/[id]/status
POST /api/resources/[id]/control

Conversation APIs

Manage conversations and message history

GET /api/conversations
POST /api/conversations
GET /api/conversations/[id]/messages

Admin APIs

Administrative operations (admin/super_admin only)

POST /api/admin/sync-models
GET /api/auth/aws-credentials
GET /api/auth/nvidia-credentials

Pricing APIs

Real-time AWS pricing data

GET /api/pricing
POST /api/pricing
POST /api/pricing/update

Common Response Formats

Success Response

{
  "success": true,
  "data": { ... },
  "message": "Operation completed successfully"
}

Error Response

{
  "success": false,
  "error": "Error message",
  "details": "Additional error details (optional)"
}

HTTP Status Codes

Status CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Authentication required or failed
403Forbidden - Insufficient permissions
404Not Found - Resource not found
500Internal Server Error - Server-side error
502Bad Gateway - External service error (AWS, NVIDIA, etc.)

Rate Limiting

Currently, there are no enforced rate limits on API endpoints. However, we recommend implementing client-side throttling for production deployments to prevent excessive API usage.

API Versioning

The current API version is v1 (implicit). Future versions will be indicated in the URL path (e.g., /api/v2/...).

CORS Configuration

Next.js API routes handle CORS automatically. For production deployments, configure CORS headers in next.config.js to restrict allowed origins.

Example Request

// Using fetch API
const response = await fetch('/api/conversations', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    title: 'My AI Assistant',
    use_case: 'general-purpose',
    deployed_resource: {
      resource_name: 'Claude Assistant',
      resource_type: 'bedrock',
      aws_resource_id: 'anthropic.claude-3-sonnet-20240229-v1:0',
      region: 'eu-north-1',
      estimated_hourly_cost: 0
    }
  })
})

const data = await response.json()

if (data.success) {
  console.log('Conversation created:', data.conversation_id)
} else {
  console.error('Error:', data.error)
}

📚 Explore API Categories

Select a category above to view detailed endpoint documentation with request/response examples.