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

​Quickstart Guide

​Prerequisites

​Step 1: Test Your API Key

​Step 2: Search and Filter

​Step 3: Get Article Details

​Step 4: Create an Article (Admin Only)

​Understanding Responses

​Success Response Structure

​Error Response Structure

​Next Steps

Explore API Reference

Authentication Guide

Error Handling

Pagination

​Common Use Cases

Quickstart Guide

Prerequisites

Step 1: Test Your API Key

Step 2: Search and Filter

Step 3: Get Article Details

Step 4: Create an Article (Admin Only)

Understanding Responses

Success Response Structure

Error Response Structure

Next Steps

Common Use Cases