Skip to main content

​
Quickstart Guide

This guide will help you make your first API call to SuprSonic in under 5 minutes.

​
Prerequisites

You’ll need:
  • A SuprSonic account
  • An API key from your dashboard
Account Context Automatic: Your API key automatically determines which account’s data you can access. No need to specify account IDs in URLs!

​
Step 1: Test Your API Key

First, let’s verify your API key works by listing your articles: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.suprsonic.com/api/v1/articles
Expected Response: 
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Getting Started with Content Marketing",
      "slug": "getting-started-content-marketing",
      "meta_description": "Learn the basics of content marketing...",
      "tags": ["marketing", "content", "seo"],
      "status": "published",
      "publish_date": "2024-01-15T10:00:00Z",
      "_links": {
        "self": "/api/v1/articles/550e8400-e29b-41d4-a716-446655440000"
      }
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

​
Step 2: Search and Filter

Try searching for specific content: 
# Search articles containing "SEO"
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suprsonic.com/api/v1/articles?q=SEO"

# Filter by tags
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suprsonic.com/api/v1/articles?tags=marketing,seo"

# Get draft articles
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://www.suprsonic.com/api/v1/articles?status=draft"

​
Step 3: Get Article Details

Fetch a complete article with full content: 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.suprsonic.com/api/v1/articles/YOUR_ARTICLE_ID

​
Step 4: Create an Article (Admin Only)

Admin API Key Required: Article creation currently requires an admin API key. Account-specific creation will be available with future scoped API keys.
curl -X POST \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "your-account-uuid",
    "title": "My New Article",
    "content": "<p>This is the article content in HTML format.</p>",
    "meta_description": "A brief description for SEO",
    "tags": ["tutorial", "api"],
    "status": "published"
  }' \
  https://www.suprsonic.com/api/v1/articles

​
Understanding Responses

​
Success Response Structure

{
  "success": true,
  "data": { /* your data */ },
  "meta": { /* pagination, links, etc. */ }
}

​
Error Response Structure

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": { /* specific error details */ }
  }
}

​
Next Steps

Explore API Reference

Browse all available endpoints and parameters

Authentication Guide

Learn about API keys and security best practices

Error Handling

Handle errors gracefully in your applications

Pagination

Work with large datasets efficiently

​
Common Use Cases

  • Content Management: List, search, and retrieve blog articles
  • Tag Organization: Filter content by topics and categories
  • Status Management: Work with drafts, published, and archived content
  • Integration: Build custom dashboards and content workflows