AirStudio Platform API Documentation

1. Base URLs

• Local API base: http://localhost:8118
• GraphQL endpoint: http://localhost:8118/graphql
• Agent API base: http://localhost:8118/agent
• Agent uploaded files: http://localhost:8118/agent-uploads/*

2. Authentication

Protected GraphQL resolvers read JWT from header:

Authorization: Bearer <token>

JWT is returned by auth mutations like:

• loginAsUser
• loginAsUserWithOtp
• registerAsUser
• registerAsSeller

3. REST Endpoints

Core media / utility endpoints

Static file serving

4. Agent API (Chatbot API)

Endpoints

Request

• sessionId (required)
• message (required)
• jwtToken (optional; pass empty string to clear)
• fileUrls (optional)
• preferredLanguage (en | ur | ur-roman | hi)

Response

• reply
• toolCalls
• sessionId
• suggestions
• metadata

Admin analytics

Agent tool groups

Auth tools

register_as_user register_as_seller login_user verify_otp request_password_reset reset_password

Store tools

create_store update_store become_seller create_store_address get_my_stores update_store_status

Product tools

list_categories list_brands create_product create_variant delete_product get_my_products update_product

Printful tools

get_printful_auth_url authenticate_printful sync_printful_product update_synced_product run_printful_get

Order tools

create_order get_orders accept_order reject_order change_order_status

Bulk tools

bulk_upload_products_csv generate_product_description

5. GraphQL API Overview

GraphQL schema is modular and defined under src/types/*.

Major domains

• Auth and identity
• Users, addresses
• Stores and store addresses
• Categories, brands, tags
• Products, variants, new arrivals, sales
• Orders, payments, order logs
• Reviews, chats, notifications
• Subscriptions, packages, coupons
• Printful auth/sync
• Blogs and comments
• Contact, newsletter

Frequently used queries

• me, meAdmin
• products, productById, colors, sizes, saleItems, bestProducts
• stores, storeById, bestStores, favoriteSeller
• orders, orderById
• activeSubscriptionByStoreId, activeSubscriptionByUserId
• allPackages, activePackages

Frequently used mutations

Auth

• loginAsUser, loginAsUserWithOtp, registerAsUser, registerAsSeller
• forgotPassword, verifyResetToken, resetPassword

Store

• createStore, becomeSeller, updateStore, updateStoreStatus
• createStoreAddress, updateStoreAddress, deleteStoreAddress

Product

• createProduct, updateProduct, updateServiceProduct
• createVariant, updateVariant
• deleteProduct, restoreProduct
• AddOrRemoveFavoriteProduct, AddToRecentlyViewProducts, ViewProduct

Order

• createOrder, acceptOrder, rejectOrder, changeOrderStatus

Subscription

• paytabSubscriptionRequest, updateSubscriptionStatus
• createSubscription (admin), activateOrDeactivateSubscription

6. Business Rules

• Store/product website visibility depends on both:
  • Store status (ACTIVE / APPROVED)
  • Active, non-expired subscription
• products query applies visibility filtering via backend helper logic.
• Seller account status can block login (PENDING, REJECTED, BANNED, etc.).
• Agent create_product flow enforces active subscription check before creation.

7. Example Requests

GraphQL — Login

POST /graphql
Content-Type: application/json

{
  "query": "mutation($email:String!,$password:String!){ loginAsUser(email:$email,password:$password){ token otpRequired user{ id firstName email role } } }",
  "variables": {
    "email": "user@example.com",
    "password": "secret"
  }
}

GraphQL — Fetch products

POST /graphql
Content-Type: application/json

{
  "query": "query($storeId:String){ products(storeId:$storeId, withoutPagination:true){ id name type thumbnail price Variants{ id name color size price thumbnail_url preview_url } } }",
  "variables": {
    "storeId": "STORE_ID"
  }
}

Agent chat

POST /agent/chat
Content-Type: application/json

{
  "sessionId": "your-session-id",
  "message": "Login karna hai",
  "jwtToken": ""
}

8. Environment Notes

Important env vars used by API: