Creator API

The Creator API provides endpoints for managing your Artbase storefront, including products, variants, orders, analytics, and account settings. These endpoints require authentication with an organization-scoped API key.

Authentication

All Creator API endpoints require a valid API key with organization access:

curl -X GET "https://api.artbase.studio/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY"

Available Endpoints

Endpoint	Description
/api/products	Manage products
/api/products/[id]/variants	Manage product variants
/api/dashboard/orders	View and manage orders
/api/analytics	Revenue and performance metrics
/api/settings/*	Account and storefront settings
/api/organizations/check-slug	Check slug availability
/api/guest/status	Guest workspace status

---

Products

List Products

GET /api/products

Retrieve all products for your organization.

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID
status	string	Filter by status: active, draft, archived
search	string	Search products by title

Response:

{
  "products": [
    {
      "id": "prod_abc123",
      "title": "Mountain Sunset",
      "slug": "mountain-sunset",
      "description": "A beautiful sunset over mountains",
      "status": "active",
      "featured": false,
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "product_images": [...],
      "product_variants": [...]
    }
  ]
}

Create Product

POST /api/products

Create a new product.

Request Body:

{
  "org_id": "org_123",
  "title": "Ocean Waves",
  "slug": "ocean-waves",
  "description": "Crashing waves at sunset",
  "status": "draft",
  "product_type": "print"
}

Response: Returns the created product object.

Get Product

GET /api/products/[id]

Retrieve a single product by ID.

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID

Update Product

PUT /api/products/[id]

Update product details.

Request Body:

{
  "org_id": "org_123",
  "title": "Updated Title",
  "status": "active"
}

Delete Product

DELETE /api/products/[id]

Delete a product (soft delete).

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID

---

Product Variants

List Variants

GET /api/products/[id]/variants

Get all variants for a product.

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID

Response:

{
  "variants": [
    {
      "id": "var_123",
      "title": "8x10 Print",
      "price": 45.00,
      "compare_at_price": 55.00,
      "inventory_quantity": 100,
      "sku": "MS-8X10",
      "is_default": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create Variant

POST /api/products/[id]/variants

Add a variant to a product.

Request Body:

{
  "org_id": "org_123",
  "title": "12x16 Print",
  "price": 75.00,
  "inventory_quantity": 50,
  "sku": "MS-12X16"
}

Update Variant

PUT /api/products/[id]/variants/[variantId]

Update variant details.

Delete Variant

DELETE /api/products/[id]/variants/[variantId]

Remove a variant.

---

Orders

List Orders

GET /api/dashboard/orders

Get orders for your organization with pagination.

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID
status	string	Filter by status
search	string	Search by order number or customer
page	number	Page number (default: 1)
per_page	number	Items per page (default: 20, max: 100)

Response:

{
  "orders": [
    {
      "id": "ord_123",
      "order_number": "ORD-2024-0001",
      "status": "pending",
      "payment_status": "paid",
      "subtotal": 95.00,
      "shipping_cost": 8.50,
      "tax_amount": 7.60,
      "total": 111.10,
      "customer_email": "buyer@example.com",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 47,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Get Order Details

GET /api/dashboard/orders/[id]

Get full order details including items and shipping.

---

Analytics

Get Analytics

GET /api/analytics

Retrieve revenue and performance metrics.

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID
days	number	Period in days (default: 30)

Response:

{
  "revenue": {
    "total": 2450.00,
    "currency": "USD"
  },
  "orders": {
    "total": 23,
    "completed": 18,
    "pending": 5
  },
  "topProducts": [
    {
      "id": "prod_abc",
      "title": "Mountain Sunset",
      "revenue": 890.00,
      "quantity": 12
    }
  ]
}

---

Settings

Storefront Settings

GET /api/settings/storefront PUT /api/settings/storefront

Manage storefront appearance and content.

Fields:

Field	Type	Description
bio	string	Artist bio/description
social_links	object	Social media links
theme	string	Theme name
custom_colors	object	Custom color overrides

Account Settings

GET /api/settings/account PUT /api/settings/account

Manage profile and account details.

Fields:

Field	Type	Description
display_name	string	Display name
email	string	Email address
avatar_url	string	Profile image URL

Notification Settings

GET /api/settings/notifications PUT /api/settings/notifications

Configure notification preferences.

Fields:

Field	Type	Description
email_orders	boolean	Order notifications
email_marketing	boolean	Marketing updates
email_digest	string	Digest frequency: daily, weekly, none

---

Organization Utilities

Check Slug Availability

GET /api/organizations/check-slug

Check if a slug is available for a new organization.

Query Parameters:

Parameter	Type	Description
slug	string	Required. Slug to check
exclude_org_id	string	Exclude existing org (for updates)

Response:

{
  "available": true,
  "slug": "my-art-studio"
}

---

Guest Workspace

Get Guest Status

GET /api/guest/status

Check if current organization is a guest workspace and get expiration details.

Query Parameters:

Parameter	Type	Description
org_id	string	Required. Organization ID

Response:

{
  "organizationId": "org_123",
  "organizationName": "My Studio",
  "isGuest": true,
  "expiresAt": "2024-01-22T10:30:00Z",
  "daysRemaining": 5,
  "isExpired": false,
  "canPromote": true
}

For non-guest workspaces:

{
  "organizationId": "org_456",
  "organizationName": "Pro Studio",
  "isGuest": false,
  "expiresAt": null,
  "daysRemaining": null,
  "isExpired": false,
  "canPromote": false
}

---

Error Handling

All endpoints return consistent error responses:

{
  "error": "Resource not found"
}

Common HTTP Status Codes:

Code	Description
200	Success
201	Created
400	Bad request - missing or invalid parameters
401	Unauthorized - invalid or missing auth
403	Forbidden - insufficient permissions
404	Not found
500	Server error

---

Next Steps

• Gallery API Reference
• Database Schema
• Webhooks