API Reference

Welcome to the AI Agent Storefront API documentation. This API allows you to programmatically access and manage AI agents, workflows, and integrations. You can use our API to build custom applications, automate workflows, and integrate our AI capabilities into your existing systems.

https://api.aiagent-storefront.com/v1

curl -X GET "https://api.aiagent-storefront.com/v1/agents" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

import { AIAgentClient } from '@aiagent-storefront/sdk';
const client = new AIAgentClient('YOUR_API_KEY');
async function getAgents() {
try {
const agents = await client.agents.list();
console.log(agents);
} catch (error) {
console.error('Error fetching agents:', error);
}
}

from aiagent_storefront import AIAgentClient
client = AIAgentClient('YOUR_API_KEY')
try:
agents = client.agents.list()
print(agents)
except Exception as e:
print(f"Error fetching agents: {e}")

require 'aiagent_storefront'
client = AIAgentStorefront::Client.new(api_key: 'YOUR_API_KEY')
begin
agents = client.agents.list
puts agents
rescue AIAgentStorefront::Error => e
puts "Error fetching agents: #{e.message}"
end

<?php
require_once 'vendor/autoload.php';
$client = new \AIAgentStorefront\Client('YOUR_API_KEY');
try {
$agents = $client->agents->list();
print_r($agents);
} catch (\AIAgentStorefront\Exception\ApiException $e) {
echo 'Error fetching agents: ' . $e->getMessage();
}

Authentication

All API requests must include an API key in the Authorization header. You can generate an API key from your account dashboard.

Authorization: Bearer YOUR_API_KEY

API Key Permissions

You can create API keys with different permission levels:

API Key Management

We recommend rotating your API keys periodically for security. You can create new API keys and delete old ones from your account dashboard.

Errors

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with our servers.

Error Response Format

All error responses include a JSON object with the following properties:

{
"error": {
"code": "invalid_request",
"message": "The request was unacceptable, often due to missing a required parameter.",
"status": 400,
"details": {
"missing_fields": ["name"]
}
}
}

Common Error Codes

Rate Limits

To ensure the stability of our API and provide fair usage for all users, we implement rate limits on API requests. Rate limits vary based on your subscription plan.

Rate Limit Headers

All API responses include headers that provide information about your current rate limit status:

Rate Limit Exceeded

If you exceed the rate limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1617203146
{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please retry after 30 seconds.",
"status": 429
}
}

Versioning

Our API uses versioning to ensure backward compatibility as we evolve the platform. The current version is v1, which is included in the URL path.

https://api.aiagent-storefront.com/v1/agents

Version Lifecycle

We follow these principles for API versioning:

• New features and non-breaking changes are added to the current version
• Breaking changes trigger a new version
• We maintain at least two versions simultaneously
• We provide at least 6 months notice before deprecating a version

Version Header

You can also specify the API version using the X-API-Version header:

X-API-Version: v1

Agents

curl -X GET "https://api.aiagent-storefront.com/v1/agents?limit=10&category=sales" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"

import { AIAgentClient } from '@aiagent-storefront/sdk';
const client = new AIAgentClient('YOUR_API_KEY');
async function listAgents() {
try {
const agents = await client.agents.list({
limit: 10,
category: 'sales'
});
console.log(agents);
} catch (error) {
console.error('Error listing agents:', error);
}
}

from aiagent_storefront import AIAgentClient
client = AIAgentClient('YOUR_API_KEY')
try:
agents = client.agents.list(
limit=10,
category='sales'
)
print(agents)
except Exception as e:
print(f"Error listing agents: {e}")

{
"data": [
{
"id": "agt_1234567890",
"name": "SalesGPT Pro",
"description": "AI-powered sales assistant that qualifies leads and books meetings",
"category": "sales",
"status": "active",
"created_at": "2025-03-15T14:30:45Z",
"updated_at": "2025-04-10T09:12:33Z",
"capabilities": ["lead_qualification", "meeting_scheduling", "follow_up"],
"pricing": {
"monthly": 49,
"yearly": 490,
"currency": "USD"
}
},
{
"id": "agt_0987654321",
"name": "ContentWizard",
"description": "Multi-format content creator for blogs, social media, and ads",
"category": "marketing",
"status": "active",
"created_at": "2025-02-20T11:15:22Z",
"updated_at": "2025-04-08T16:45:10Z",
"capabilities": ["blog_writing", "social_media_posts", "ad_copy"],
"pricing": {
"monthly": 39,
"yearly": 390,
"currency": "USD"
}
}
],
"meta": {
"total": 42,
"limit": 10,
"offset": 0
}
}

API Console

Test API requests directly from your browser. Select an endpoint, customize parameters, and see the response in real-time.

// Response will appear here after sending a request

SDKs & Libraries

We provide official SDKs for multiple programming languages to make integration with our API even easier.

npm install @aiagent-storefront/sdk

import { AIAgentClient } from '@aiagent-storefront/sdk';
// Initialize the client with your API key
const client = new AIAgentClient('YOUR_API_KEY');
// List agents
async function listAgents() {
try {
const agents = await client.agents.list({
limit: 10,
category: 'sales'
});
console.log(agents);
} catch (error) {
console.error('Error:', error);
}
}
// Execute a workflow
async function executeWorkflow() {
try {
const result = await client.workflows.execute('wf_1234567890', {
input: {
customer_name: 'John Doe',
email: 'john@example.com'
}
});
console.log(result);
} catch (error) {
console.error('Error:', error);
}
}