API Endpoints

Overview & Getting Started

Resources

Agent CapabilitiesPrompt Best PracticesE-commerce IntegrationHealthcare Integration

SparkCo API Documentation

Welcome to SparkCo's API documentation. Our API enables you to integrate AI-powered calling and messaging capabilities into your applications.

Getting Started

1. Get Your API Key

Generate an API key from your SparkCo dashboard to authenticate your requests.

# Navigate to Settings → API Keys in your dashboard
# Click "Generate New Key" and save it securely
API_KEY=sk_live_...

2. Make Your First Request

Test your API key with a simple request to list your agents.

curl https://api.sparkco.ai/api/v1/agents \
-H "X-API-Key: your-api-key"

Core Concepts

Agents

AI agents that can engage in natural conversations with your recipients. Each agent has a specific purpose and personality.

Recipients

The people your agents communicate with. Each recipient has their own conversation history and preferences.

Schedules & Reminders

Automated communications that can be scheduled for specific times or set up as recurring messages.

Knowledge Base

Custom knowledge that agents can reference during conversations, ensuring accurate and relevant responses.

Integration Best Practices

Authentication

Include your API key in the X-API-Key header with every request.

// JavaScript
const response = await fetch('https://api.sparkco.ai/api/v1/agents', {
  headers: {
    'X-API-Key': 'your-api-key'
  }
});
# Python
import requests

response = requests.get(
    'https://api.sparkco.ai/api/v1/agents',
    headers={'X-API-Key': 'your-api-key'}
)

Error Handling

All responses include a success field and standardized error codes.

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Detailed error message"
  }
}

Rate Limiting

Implement exponential backoff for retries and cache responses when possible. Rate limits are included in response headers:

  • X-RateLimit-Limit: Requests allowed per window
  • X-RateLimit-Remaining: Requests remaining in window
  • X-RateLimit-Reset: Time until limit resets

Common Workflows

Setting Up an Agent

  1. Create an agent with a specific purpose
  2. Upload relevant documents to the knowledge base
  3. Create recipients to interact with the agent
  4. Set up schedules or initiate calls

Automated Communications

  1. Create a schedule for recurring calls
  2. Set up reminders for specific events
  3. Monitor call history and summaries
  4. Adjust agent behavior based on feedback

Available Endpoints

POST
/api/v1/agents
Create and manage AI agents
POST
/api/v1/recipients
Manage recipient profiles
POST
/api/v1/schedules
Schedule automated communications
POST
/api/v1/knowledge
Upload and manage knowledge base

Need Help?

If you have any questions or need assistance, our support team is here to help:

  • Email us at support@sparkco.ai
  • Join our Discord community for real-time help
  • Check out our GitHub repository for example integrations