Skip to main content

API Overview

The Artbase API enables developers to build custom integrations, automate workflows, and extend platform functionality. This reference covers available endpoints, authentication, and best practices.

Base URL​

All API requests use the following base URL:

https://api.artbase.studio/v1

For storefront-specific requests:

https://{org-slug}.artbase.studio/api/v1

Authentication​

The Artbase API uses bearer token authentication. Include your API key in the Authorization header:

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

Obtaining API Keys​

  1. Open Creator Hub
  2. Go to Settings > API
  3. Click Generate New Key
  4. Copy and securely store the key

API keys are organization-scoped. Each key only accesses data within its organization.

Key Security​

  • Never expose keys in client-side code
  • Rotate keys periodically
  • Use environment variables in applications
  • Revoke compromised keys immediately

Request Format​

Headers​

All requests should include:

HeaderValueRequired
AuthorizationBearer YOUR_API_KEYYes
Content-Typeapplication/jsonFor POST/PUT/PATCH
Acceptapplication/jsonRecommended

Request Body​

POST, PUT, and PATCH requests accept JSON bodies:

curl -X POST "https://api.artbase.studio/v1/products" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Mountain Sunset",
    "product_type": "original",
    "base_price": 450.00
  }'

Response Format​

Success Responses​

Successful requests return JSON with the requested data:

{
  "data": {
    "id": "prod_abc123",
    "title": "Mountain Sunset",
    "product_type": "original",
    "base_price": 450.00,
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List Responses​

List endpoints return paginated results:

{
  "data": [
    { "id": "prod_abc123", "title": "Mountain Sunset" },
    { "id": "prod_def456", "title": "Ocean Waves" }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Error Responses​

Errors include a code and message:

{
  "error": {
    "code": "invalid_request",
    "message": "The 'title' field is required",
    "details": {
      "field": "title",
      "reason": "missing_required_field"
    }
  }
}

HTTP Status Codes​

CodeMeaning
200Success
201Created successfully
204Success, no content returned
400Bad request - check your parameters
401Unauthorized - invalid or missing API key
403Forbidden - insufficient permissions
404Resource not found
422Validation error
429Rate limit exceeded
500Server error

Pagination​

List endpoints support pagination parameters:

ParameterDefaultMaxDescription
page1-Page number
per_page20100Items per page

Example:

GET /v1/products?page=2&per_page=50

Cursor Pagination​

High-volume endpoints use cursor-based pagination:

{
  "data": [...],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6MTAwfQ=="
  }
}

Use the cursor for the next page:

GET /v1/orders?cursor=eyJpZCI6MTAwfQ==

Rate Limits​

API requests are rate-limited per organization:

PlanRequests/MinuteRequests/Day
Starter605,000
Growth12020,000
Pro300100,000

Rate Limit Headers​

Responses include rate limit information:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1704067200

Handling Rate Limits​

When rate limited (429 response):

  1. Check X-RateLimit-Reset for reset time
  2. Implement exponential backoff
  3. Queue non-urgent requests
  4. Contact support if limits are insufficient

Filtering & Sorting​

Filtering​

Most list endpoints support filtering:

GET /v1/products?status=active&product_type=print

Common filter operators:

OperatorExampleDescription
=status=activeExact match
!=status!=archivedNot equal
>=price>=100Greater than or equal
<=price<=500Less than or equal
instatus[in]=active,draftIn list

Sorting​

Control result ordering:

GET /v1/products?sort=-created_at,title
  • Prefix with - for descending order
  • Multiple fields separated by comma

Expanding Relations​

Request related data using expand:

GET /v1/orders/ord_123?expand=customer,items

Response includes expanded objects:

{
  "data": {
    "id": "ord_123",
    "customer": {
      "id": "cust_456",
      "name": "Jane Smith",
      "email": "jane@example.com"
    },
    "items": [
      { "id": "item_789", "title": "Mountain Sunset", "quantity": 1 }
    ]
  }
}

Versioning​

The API is versioned via URL path (/v1/). Breaking changes trigger new versions.

Current version: v1

Deprecation Policy​

  • Deprecated features announced 6 months in advance
  • Old versions supported for 12 months after deprecation
  • Deprecation warnings included in response headers

SDKs & Libraries​

Official SDKs are available for common languages:

LanguagePackageStatus
JavaScript/TypeScript@artbase/sdkAvailable
Pythonartbase-pythonComing soon
Rubyartbase-rubyComing soon

JavaScript SDK Example​

import { ArtbaseClient } from '@artbase/sdk';

const client = new ArtbaseClient({
  apiKey: process.env.ARTBASE_API_KEY
});

// List products
const products = await client.products.list({
  status: 'active',
  limit: 50
});

// Create order
const order = await client.orders.create({
  customer_email: 'buyer@example.com',
  items: [
    { variant_id: 'var_123', quantity: 1 }
  ]
});

Testing​

Sandbox Environment​

Test integrations using the sandbox:

https://api.sandbox.artbase.studio/v1

Sandbox features:

  • Isolated from production data
  • Test payment processing
  • Reset data at will
  • No rate limits

Test API Keys​

Generate sandbox keys separately from production:

  1. Go to Settings > API
  2. Switch to Sandbox tab
  3. Generate sandbox key

Support​

API Status​

Check real-time API status at status.artbase.studio

Getting Help​

Next Steps​