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
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
