API Reference v1

Name: GoCodeMe
Author: GoSiteMe

Complete REST API documentation for the Alfred AI platform. All endpoints use JSON, return structured responses, and support API Key & OAuth2 authentication.

Overview

Base URL: https://gositeme.com/api/v1/ — All endpoint paths below are relative to this base.

The Alfred API v1 is a RESTful JSON API organized around 7 core resources:

Resource	Base Path	Description
`agents`	/agents	Create, manage, and execute AI agents
`chat`	/chat	Conversational AI with streaming support
`tools`	/tools	875+ tools — search, discover, execute
`fleets`	/fleets	Multi-agent fleet orchestration
`voice`	/voice	Voice calls & conference rooms
`marketplace`	/marketplace	Browse & install community extensions
`usage`	/usage	Usage metrics & billing

Response Envelope

Successful responses return a data key (single resource) or paginated envelope:

JSON — Single Resource

{
  "data": { "id": 1, "agent_name": "Support Bot", "status": "idle" }
}

JSON — Paginated

{
  "data": [ ... ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

All paginated endpoints accept ?page=N&per_page=N (max 100).

Request Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <api_key or oauth_token>`
`Content-Type`	POST/PUT	`application/json`
`X-Request-ID`	No	Client-generated request ID for tracing

Authentication

The API supports three authentication methods:

1. API Key (Recommended)

Create API keys in the Developer Portal. Keys use the format ak_live_<prefix>_<secret> (production) or ak_test_<prefix>_<secret> (sandbox).

cURL

curl https://gositeme.com/api/v1/tools \
  -H "Authorization: Bearer ak_live_abc123_secretkey456"

import { AlfredClient } from '@alfredai/sdk';
const alfred = new AlfredClient({ apiKey: 'ak_live_abc123_secretkey456' });

from alfred_sdk import AlfredClient
client = AlfredClient(api_key="ak_live_abc123_secretkey456")

$alfred = new \AlfredAI\Alfred(['api_key' => 'ak_live_abc123_secretkey456']);

2. OAuth2 Bearer Token

OAuth apps receive tokens prefixed with aat_. Register your app in the Developer Portal to get client credentials.

cURL

curl https://gositeme.com/api/v1/agents \
  -H "Authorization: Bearer aat_your_oauth_token_here"

3. Session Token (Legacy)

Session tokens from /api/auth.php (prefix sess_) are still supported for backward compatibility.

API keys in query parameters (?api_key=...) are supported for testing but not recommended for production — URLs may be logged by proxies and servers.

Scopes

API keys and OAuth tokens can be scoped to specific permissions:

Scope	Description
`*`	Full access (default for API keys)
`agents:read`	Read agent data
`agents:write`	Create, update, delete agents
`chat:read`	Read chat endpoint info
`chat:write`	Send chat messages
`tools:read`	List and search tools
`tools:execute`	Execute tools
`fleets:read`	Read fleet data
`fleets:write`	Create, manage fleets
`voice:read`	Read call/room data
`voice:write`	Create rooms, start calls
`marketplace:read`	Browse marketplace
`marketplace:write`	Install marketplace items
`usage:read`	View usage data

Agents

Create, manage, and execute AI agents. Agents can be assigned roles, skills, voice capabilities, and attached to fleets.

POST /agents — Create Agent

POST /agents

Parameter	Type	Required	Description
`agent_name`	string	Yes	Display name (max 100 chars)
`agent_role`	string	Yes	`leader`, `specialist`, `generalist`, `reviewer`
`task`	string	No	Initial task description (max 2000 chars)
`skills`	string[]	No	Array of tool names the agent can use
`fleet_id`	integer	No	Fleet to attach the agent to
`voice_enabled`	boolean	No	Enable voice interaction
`voice_engine`	string	No	`kokoro`, `orpheus`, `cartesia`, `elevenlabs`

cURL

curl -X POST https://gositeme.com/api/v1/agents \
  -H "Authorization: Bearer ak_live_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "Support Bot",
    "agent_role": "specialist",
    "task": "Handle customer billing questions",
    "skills": ["product_lookup", "ticket_create"],
    "voice_enabled": true,
    "voice_engine": "cartesia"
  }'

const agent = await alfred.agents.create({
  agent_name: 'Support Bot',
  agent_role: 'specialist',
  task: 'Handle customer billing questions',
  skills: ['product_lookup', 'ticket_create'],
  voice_enabled: true,
  voice_engine: 'cartesia',
});

agent = client.agents.create(
    agent_name="Support Bot",
    agent_role="specialist",
    task="Handle customer billing questions",
    skills=["product_lookup", "ticket_create"],
    voice_enabled=True,
    voice_engine="cartesia",
)

$agent = $alfred->agents->create([
    'agent_name' => 'Support Bot',
    'agent_role' => 'specialist',
    'task' => 'Handle customer billing questions',
    'skills' => ['product_lookup', 'ticket_create'],
    'voice_enabled' => true,
    'voice_engine' => 'cartesia',
]);

GET /agents — List Agents

GET /agents

Returns a paginated list of the authenticated user's agents.

cURL

curl "https://gositeme.com/api/v1/agents?page=1&per_page=10" \
  -H "Authorization: Bearer ak_live_xxx_yyy"

GET /agents/{id} — Get Agent

GET /agents/{id}

Response

{
  "data": {
    "id": 42,
    "agent_name": "Support Bot",
    "agent_role": "specialist",
    "task": "Handle customer billing questions",
    "skills": ["product_lookup", "ticket_create"],
    "fleet_id": null,
    "status": "idle",
    "voice_enabled": true,
    "voice_engine": "cartesia",
    "created_at": "2026-03-04T12:00:00Z",
    "updated_at": "2026-03-04T12:00:00Z"
  }
}

PUT /agents/{id} — Update Agent

PUT /agents/{id}

Update any mutable agent fields. Only include fields you want to change.

DELETE /agents/{id} — Delete Agent

DELETE /agents/{id}

POST /agents/{id}/execute — Execute Task

POST /agents/{id}/execute

Send a message to an agent and receive a response with tool usage details.

Parameter	Type	Required	Description
`message`	string	Yes	Task or message for the agent
`tools`	string[]	No	Override available tools for this execution
`context`	object	No	Additional context data

Response

{
  "data": {
    "reply": "I looked up the account and created support ticket #1234.",
    "tools_used": ["product_lookup", "ticket_create"],
    "execution_time_ms": 2340
  }
}

POST /agents/{id}/deploy — Deploy Agent

POST /agents/{id}/deploy

Deploy an agent to start accepting tasks. Returns the updated agent with status: "working".

Chat

Send messages to Alfred AI and receive responses. Supports streaming via Server-Sent Events.

POST /chat — Send Message

POST /chat

Parameter	Type	Required	Description
`message`	string	Yes	Message (max 10,000 chars)
`conversation_id`	string	No	Continue existing conversation
`model`	string	No	AI model (default: `alfred-default`)
`temperature`	float	No	0.0–1.0 creativity (default: 0.7)
`tools`	string[]	No	Tools to make available
`stream`	boolean	No	Enable SSE streaming (default: false)

cURL

curl -X POST https://gositeme.com/api/v1/chat \
  -H "Authorization: Bearer ak_live_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are the DNS records for example.com?",
    "tools": ["dns_lookup"],
    "temperature": 0.5
  }'

Response (Non-Streaming)

JSON

{
  "data": {
    "reply": "Here are the DNS records for example.com...",
    "conversation_id": "conv_abc123",
    "model": "alfred-default",
    "tools_used": ["dns_lookup"],
    "tokens_used": 347,
    "execution_time_ms": 1240
  }
}

Streaming (SSE)

Set "stream": true to receive Server-Sent Events. Each event contains a JSON chunk:

SSE Stream

data: {"type":"text","content":"Here are "}
data: {"type":"text","content":"the DNS records..."}
data: {"type":"tool_start","tool":"dns_lookup"}
data: {"type":"tool_end","tool":"dns_lookup"}
data: {"type":"done","conversation_id":"conv_abc123"}
data: [DONE]

for await (const chunk of alfred.chat.stream({ message: 'Explain DNS' })) {
  if (chunk.type === 'text') process.stdout.write(chunk.content || '');
}

for chunk in client.chat.stream("Explain DNS"):
    if chunk.get("type") == "text":
        print(chunk["content"], end="", flush=True)

$alfred->chat->stream('Explain DNS', function($chunk) {
    if ($chunk['type'] === 'text') echo $chunk['content'];
});

GET /chat — List Conversations

GET /chat

Returns a paginated list of recent conversations.

Tools

Search, discover, and execute 875+ tools across 17 categories — legal, healthcare, devops, security, analytics, and more.

GET /tools — List Tools

GET /tools

Parameter	Type	Required	Description
`search` / `q`	string	No	Search query
`category`	string	No	Filter by category slug
`tier`	string	No	Filter by tier (free, starter, pro, enterprise)
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Results per page (max: 100)

cURL

curl "https://gositeme.com/api/v1/tools?search=dns&category=devops&per_page=5" \
  -H "Authorization: Bearer ak_live_xxx_yyy"

GET /tools/categories — List Categories

GET /tools/categories

Response

{
  "data": [
    { "slug": "legal", "name": "Legal", "count": 85 },
    { "slug": "healthcare", "name": "Healthcare", "count": 62 },
    { "slug": "devops", "name": "DevOps", "count": 94 },
    { "slug": "security", "name": "Security", "count": 71 }
  ]
}

GET /tools/{name} — Get Tool Details

GET /tools/{name}

Returns tool metadata including JSON Schema input definition.

Response

{
  "data": {
    "name": "dns_lookup",
    "description": "Look up DNS records for a domain",
    "category": "devops",
    "tier": "free",
    "input_schema": {
      "type": "object",
      "properties": {
        "domain": { "type": "string", "description": "Domain name to look up" },
        "type": { "type": "string", "enum": ["A","AAAA","MX","NS","TXT","CNAME"], "default": "A" }
      },
      "required": ["domain"]
    },
    "tags": ["dns", "network", "devops"]
  }
}

POST /tools/{name}/execute — Execute Tool

POST /tools/{name}/execute

Parameter	Type	Required	Description
`args`	object	Yes	Tool-specific arguments (see tool's input_schema)

cURL

curl -X POST https://gositeme.com/api/v1/tools/dns_lookup/execute \
  -H "Authorization: Bearer ak_live_xxx_yyy" \
  -H "Content-Type: application/json" \
  -d '{"args": {"domain": "example.com", "type": "A"}}'

const result = await alfred.tools.execute('dns_lookup', {
  args: { domain: 'example.com', type: 'A' },
});
console.log(result.data.result); // { records: [...] }

result = client.tools.execute("dns_lookup", args={"domain": "example.com", "type": "A"})
print(result["data"]["result"])

$result = $alfred->tools->execute('dns_lookup', ['domain' => 'example.com', 'type' => 'A']);
print_r($result['data']['result']);

Execution Response

JSON

{
  "data": {
    "tool": "dns_lookup",
    "result": {
      "records": [
        { "type": "A", "value": "93.184.216.34", "ttl": 300 }
      ]
    },
    "execution_time_ms": 142,
    "credits_used": 1
  }
}

Fleets

Orchestrate multiple agents as a fleet. Fleets support parallel execution, auto-scaling, and round-robin task distribution.

POST /fleets — Create Fleet

POST /fleets

Parameter	Type	Required	Description
`name`	string	Yes	Fleet display name
`description`	string	No	Fleet description
`max_agents`	integer	No	Maximum agent slots (default: 5)
`auto_scale`	boolean	No	Enable auto-scaling (default: false)

GET /fleets — List Fleets

GET /fleets

GET /fleets/{id} — Get Fleet

GET /fleets/{id}

Response

{
  "data": {
    "id": 7,
    "name": "Support Team",
    "description": "Customer support agents",
    "status": "active",
    "max_agents": 10,
    "auto_scale": true,
    "agent_count": 3,
    "tasks_completed": 1247,
    "created_at": "2026-03-01T10:00:00Z"
  }
}

PUT /fleets/{id} — Update Fleet

PUT /fleets/{id}

DELETE /fleets/{id} — Delete Fleet

DELETE /fleets/{id}

POST /fleets/{id}/deploy — Deploy Fleet

POST /fleets/{id}/deploy

Parameter	Type	Required	Description
`task`	string	No	Task for the fleet to execute
`strategy`	string	No	`parallel`, `sequential`, `round-robin`
`timeout`	integer	No	Timeout in seconds

Voice

Voice calls and AI-powered conference rooms. Supports Kokoro, Orpheus, Cartesia, and ElevenLabs engines.

GET /voice/calls — List Call History

GET /voice/calls

Returns a paginated list of voice calls.

GET /voice/calls/{id} — Get Call Details

GET /voice/calls/{id}

Response

{
  "data": {
    "id": 156,
    "room_name": "Sales Call",
    "status": "completed",
    "duration_seconds": 340,
    "participants": 2,
    "voice_engine": "cartesia",
    "transcript": "Agent: Hello, how can I help today?...",
    "created_at": "2026-03-04T14:30:00Z"
  }
}

POST /voice/rooms — Create Room

POST /voice/rooms

Parameter	Type	Required	Description
`name`	string	Yes	Room name
`max_participants`	integer	No	Max participants (default: 10)
`voice_engine`	string	No	`kokoro`, `orpheus`, `cartesia`, `elevenlabs`
`agent_id`	integer	No	AI agent to join the room

GET /voice/rooms — List Active Rooms

GET /voice/rooms

GET /voice/rooms/{id} — Get Room Details

GET /voice/rooms/{id}

POST /voice/calls — Start Outbound Call

POST /voice/calls

Parameter	Type	Required	Description
`to`	string	Yes	Phone number (E.164) or SIP URI
`agent_id`	integer	No	Agent to handle the call
`voice_engine`	string	No	Voice engine override

Marketplace

Browse and install community-created agents, tools, fleet templates, and extensions.

GET /marketplace — List Items

GET /marketplace

Parameter	Type	Required	Description
`search`	string	No	Search query
`type`	string	No	`agent`, `tool`, `fleet_template`, `extension`
`sort`	string	No	`popular`, `newest`, `rating`

GET /marketplace/{id} — Get Item Details

GET /marketplace/{id}

POST /marketplace/{id}/install — Install Item

POST /marketplace/{id}/install

Usage

Monitor API usage, tool executions, and billing metrics.

GET /usage — Current Period Summary

GET /usage

Response

{
  "data": {
    "period": "2026-03",
    "plan": "professional",
    "api_calls": { "used": 4521, "limit": null },
    "tools_executed": { "used": 892, "limit": null },
    "agents_active": { "used": 3, "limit": 20 },
    "fleets_active": { "used": 1, "limit": 10 },
    "voice_minutes": { "used": 45, "limit": 500 },
    "storage_mb": { "used": 128, "limit": 5120 }
  }
}

GET /usage/history — Historical Records

GET /usage/history

Parameter	Type	Required	Description
`start_date`	string	No	ISO date (e.g. 2026-03-01)
`end_date`	string	No	ISO date
`resource_type`	string	No	Filter by type (tools, agents, chat, voice)

Rate Limits

Rate limits are enforced per-key using a 1-minute sliding window. Headers are included on every response.

Free

req/min

Starter

req/min

Professional

req/min

Enterprise

200

req/min

Hourly & Daily Limits

Tier	Per Minute	Per Hour	Per Day
Free	10	100	500
Starter	30	500	5,000
Professional	60	2,000	20,000
Enterprise	200	10,000	100,000

Rate Limit Headers

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your tier
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait (only on 429 responses)

Best Practice: All official SDKs automatically handle rate limiting with exponential backoff. If making raw HTTP requests, implement retry logic on 429 responses.

Error Codes

All API errors return a consistent JSON envelope:

JSON

{
  "error": {
    "code": "validation_error",
    "message": "Missing required fields: agent_name",
    "status": 400
  }
}

Status	Code	Description
`400`	`validation_error`	Missing or invalid parameters
`401`	`auth_required`	Missing or invalid API key / OAuth token
`403`	`insufficient_scope`	Token lacks required scopes
`404`	`resource_not_found`	Resource or endpoint not found
`405`	`method_not_allowed`	HTTP method not supported for this endpoint
`429`	`rate_limit_exceeded`	Too many requests — check `Retry-After`
`500`	`internal_error`	Server error — contact support with `X-Request-ID`
`503`	`service_unavailable`	Service temporarily unavailable

import { AuthError, RateLimitError, NotFoundError } from '@alfredai/sdk';

try {
  await alfred.tools.execute('some_tool', { args: {} });
} catch (err) {
  if (err instanceof AuthError) console.error('Auth failed');
  if (err instanceof RateLimitError) console.error('Retry after ' + err.retryAfter + 's');
  if (err instanceof NotFoundError) console.error('Not found');
}

from alfred_sdk import AuthenticationError, RateLimitError, NotFoundError

try:
    client.tools.execute("some_tool", args={})
except AuthenticationError:
    print("Auth failed")
except RateLimitError as e:
    print(f"Retry in {e.retry_after}s")
except NotFoundError:
    print("Not found")

use AlfredAI\Exceptions\{AuthException, RateLimitException, NotFoundException};

try {
    $alfred->tools->execute('some_tool', []);
} catch (AuthException $e) {
    echo "Auth failed";
} catch (RateLimitException $e) {
    echo "Retry in " . $e->retryAfter . "s";
} catch (NotFoundException $e) {
    echo "Not found";
}

Webhooks

Alfred can send real-time event notifications to your application via webhooks. Configure webhook URLs in the Developer Portal.

Webhook Delivery Format

Each webhook delivery includes these headers:

Header	Description
`X-Webhook-Signature`	`sha256=<HMAC hex digest>` — HMAC-SHA256 of the payload using your webhook secret
`X-Webhook-Event`	Event name (e.g. `agent.deployed`)
`X-Webhook-Delivery`	Unique delivery ID
`User-Agent`	`Alfred-Webhooks/1.0`

Payload Format

JSON

{
  "id": "d4e5f6a7b8c9d0e1",
  "event": "agent.deployed",
  "timestamp": "2026-03-04T15:30:00+00:00",
  "data": {
    "agent_id": 42,
    "agent_name": "Support Bot",
    "fleet_id": 7,
    "status": "working"
  }
}

Available Events

Event	Description
`agent.created`	Agent was created
`agent.deployed`	Agent was deployed / started
`agent.completed`	Agent completed a task
`agent.error`	Agent encountered an error
`fleet.created`	Fleet was created
`fleet.deployed`	Fleet deployment started
`tool.executed`	Tool was executed
`voice.call.started`	Voice call started
`voice.call.ended`	Voice call ended
`voice.room.created`	Voice room created
`marketplace.installed`	Marketplace item installed
`usage.threshold`	Usage threshold reached (80%, 100%)

Signature Verification

Always verify webhook signatures to ensure requests come from Alfred. Use constant-time comparison.

// Express.js example
app.post('/webhook', express.text({ type: '*/*' }), (req, res) => {
  const event = alfred.webhooks.verifyAndParse(
    req.body,
    req.headers['x-webhook-signature'],
    process.env.WEBHOOK_SECRET,
  );
  console.log(event.event, event.data);
  res.sendStatus(200);
});

# Flask example
@app.post("/webhook")
def handle_webhook():
    event = client.webhooks.verify_and_parse(
        request.data.decode(),
        request.headers["X-Webhook-Signature"],
        WEBHOOK_SECRET,
    )
    print(f"{event['event']}: {event['data']}")
    return "", 200

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';

$verifier = new \AlfredAI\WebhookVerifier();
$event = $verifier->verifyAndParse($payload, $signature, $webhookSecret);
echo "Event: " . $event['event'];

Official SDKs

Get started faster with official client libraries that handle authentication, retries, and error handling.

Language	Package	Install
Node.js / TypeScript	`@alfredai/sdk`	`npm install @alfredai/sdk`
Python	`alfred-ai-sdk`	`pip install alfred-ai-sdk`
PHP	`alfredai/sdk`	`composer require alfredai/sdk`

View all SDKs, examples, and features on the SDKs page.

Need Help? If you encounter issues, contact support@gositeme.com with the X-Request-ID from the response headers.

API Reference v1

Overview

Response Envelope

Request Headers

Authentication

1. API Key (Recommended)

2. OAuth2 Bearer Token

3. Session Token (Legacy)

Scopes

Agents

POST /agents — Create Agent

GET /agents — List Agents

GET /agents/{id} — Get Agent

PUT /agents/{id} — Update Agent

DELETE /agents/{id} — Delete Agent

POST /agents/{id}/execute — Execute Task

POST /agents/{id}/deploy — Deploy Agent

Chat

POST /chat — Send Message

Response (Non-Streaming)

Streaming (SSE)

GET /chat — List Conversations

Tools

GET /tools — List Tools

GET /tools/categories — List Categories

GET /tools/{name} — Get Tool Details

POST /tools/{name}/execute — Execute Tool

Execution Response

Fleets

POST /fleets — Create Fleet

GET /fleets — List Fleets

GET /fleets/{id} — Get Fleet

PUT /fleets/{id} — Update Fleet

DELETE /fleets/{id} — Delete Fleet

POST /fleets/{id}/deploy — Deploy Fleet

Voice

GET /voice/calls — List Call History

GET /voice/calls/{id} — Get Call Details

POST /voice/rooms — Create Room

GET /voice/rooms — List Active Rooms

GET /voice/rooms/{id} — Get Room Details

POST /voice/calls — Start Outbound Call

Marketplace

GET /marketplace — List Items

GET /marketplace/{id} — Get Item Details

POST /marketplace/{id}/install — Install Item

Usage

GET /usage — Current Period Summary

GET /usage/history — Historical Records

Rate Limits

Hourly & Daily Limits

Rate Limit Headers

Error Codes

Webhooks

Webhook Delivery Format

Payload Format

Available Events

Signature Verification

Official SDKs

Bon retour

Créer un compte

Reset Password