Agentiv API Docs — Developer Reference

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are issued per user account and tied to your subscription plan.

🔑 Get your API key from the Agentiv Dashboard → Settings → API Keys. Pro plan required for API access.

curl https://api.agentiv.cloud/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Token Scopes

Scope	Access
agents:read	List agents and execution history
agents:run	Trigger agent executions
schedules:write	Create and modify schedules
connections:read	View integration connection status

Rate Limits

Plan	Requests/min	Agent runs/day	Concurrent
Starter	30	50	1
Pro	120	1,000+	5
Enterprise	Unlimited	Unlimited	Custom

Rate limit headers are returned on every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Error Codes

Code	HTTP	Meaning
UNAUTHORIZED	401	Invalid or missing API key
FORBIDDEN	403	Plan doesn't include this feature
NOT_FOUND	404	Agent or resource doesn't exist
RATE_LIMITED	429	Too many requests — back off and retry
INVALID_INPUT	400	Missing or malformed request body
INTEGRATION_NOT_CONNECTED	400	Required app integration not connected by user
EXECUTION_FAILED	500	Agent ran but encountered an error — retryable

{
  "success": false,
  "error": {
    "code": "INTEGRATION_NOT_CONNECTED",
    "message": "Gmail not connected. User must connect at /connections",
    "integrationSlug": "gmail"
  }
}

Run Agent

POST /api/agents/{agentSlug}/run Trigger an agent execution

Path Parameters

Parameter	Type	Description
agentSlugrequired	string	Agent identifier (see Agent Slugs)

Request Body

Field	Type	Description
input_payloadrequired	object	Agent-specific input (see per-agent schemas below)
asyncoptional	boolean	If true, returns immediately with execution_id. Default: false
webhook_urloptional	string	Receive results at this URL when done

// EmailTriage example
POST /api/agents/email-triage/run
Authorization: Bearer YOUR_API_KEY

{
  "input_payload": {
    "max_emails": 20,
    "rules": ["Flag anything from @techcorp.com as urgent"]
  },
  "async": true,
  "webhook_url": "https://your-app.com/webhooks/agentiv"
}

// Response (async mode)
{
  "success": true,
  "data": {
    "execution_id": "exec_01HXYZ123ABC",
    "agent_slug": "email-triage",
    "status": "queued",
    "estimated_duration_ms": 8000,
    "created_at": "2025-01-15T06:00:00Z"
  }
}

// Response (sync mode — waits for completion)
{
  "success": true,
  "data": {
    "execution_id": "exec_01HXYZ123ABC",
    "status": "success",
    "summary": "Triaged 18 emails | 2 urgent | 4 archived",
    "output": {
      "triaged": [...],
      "inbox_stats": { "total": 18, "urgent": 2, "archived": 4 }
    },
    "tokens_used": 4821,
    "duration_ms": 7340
  }
}

Get Execution Result

GET /api/executions/{executionId} Poll for execution result

GET /api/executions/exec_01HXYZ123ABC
Authorization: Bearer YOUR_API_KEY

// Response
{
  "success": true,
  "data": {
    "id": "exec_01HXYZ123ABC",
    "agent_slug": "email-triage",
    "status": "success",           // queued | running | success | failed
    "trigger_type": "api",
    "summary": "Triaged 18 emails | 2 urgent | 4 archived",
    "output": { ... },             // Full agent output JSON
    "tokens_used": 4821,
    "duration_ms": 7340,
    "queued_at": "2025-01-15T06:00:00Z",
    "completed_at": "2025-01-15T06:00:07Z"
  }
}

List Agents

GET /api/agents List all available agents

GET /api/agents
Authorization: Bearer YOUR_API_KEY

// Response
{
  "success": true,
  "data": [
    {
      "slug": "email-triage",
      "name": "EmailTriage",
      "description": "Autonomous inbox triage",
      "required_integrations": ["gmail"],
      "subscription_status": "active",
      "trial_ends_at": null
    },
    ...
  ]
}

Schedules

GET /api/schedules List all agent schedules

// Response
{
  "success": true,
  "data": [
    {
      "id": "sch_01HXYZ",
      "agent_slug": "email-triage",
      "enabled": true,
      "cron_expr": "0 6 * * *",
      "timezone": "Asia/Kolkata",
      "next_run_at": "2025-01-16T00:30:00Z",
      "last_run_at": "2025-01-15T00:30:00Z",
      "last_status": "success",
      "total_runs": 47
    }
  ]
}

POST /api/schedules/{agentSlug} Create or update a schedule

Field	Type	Description
cron_exprrequired	string	Cron expression e.g. "0 6 * * *"
timezonerequired	string	IANA timezone e.g. "Asia/Kolkata"
enabledoptional	boolean	Default: true
input_payloadoptional	object	Default inputs for scheduled runs

POST /api/schedules/email-triage

{
  "cron_expr": "0 6 * * 1-5",
  "timezone": "Asia/Kolkata",
  "enabled": true,
  "input_payload": { "max_emails": 30 }
}

Webhooks

Receive real-time notifications when agent executions complete, fail, or when schedules fire.

Webhook payloads are signed with HMAC-SHA256. Verify the X-Agentiv-Signature header matches HMAC-SHA256(secret, body) to authenticate requests.

Event Types

Event	Description
agent.execution.success	Agent completed successfully
agent.execution.failed	Agent failed after all retries
schedule.fired	Scheduled job started
integration.disconnected	OAuth token expired or revoked

Webhook Payload Schema

// POST https://your-app.com/webhooks/agentiv
// Headers:
//   X-Agentiv-Signature: sha256=abc123...
//   X-Agentiv-Event: agent.execution.success

{
  "event": "agent.execution.success",
  "execution_id": "exec_01HXYZ123ABC",
  "agent_slug": "email-triage",
  "user_id": "usr_01HABC",
  "status": "success",
  "summary": "Triaged 18 emails | 2 urgent | 4 archived",
  "output": { ... },
  "tokens_used": 4821,
  "duration_ms": 7340,
  "timestamp": "2025-01-15T06:00:07Z"
}

// Verify signature in Node.js:
const crypto = require('crypto');
const sig = crypto
  .createHmac('sha256', process.env.AGENTIV_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');
if (sig !== req.headers['x-agentiv-signature'].replace('sha256=', '')) {
  return res.status(401).send('Invalid signature');
}

Agent Slugs

Agent	Slug	Required Integration
📧 EmailTriage	email-triage	gmail
✍️ ProposalAI	proposal-ai	upwork (optional)
🧾 ExpenseAI	expense-ai	razorpay, bank-email
🦁 InvoiceLion	invoice-lion	quickbooks (optional)
🎯 ColdEmailAI	cold-email-ai	gmail (optional)
🤝 MeetingPrep Pro	meeting-prep	google-calendar
⚖️ ContractRedline	contract-redline	google-drive (optional)
📣 AdCopyForge	ad-copy-forge	meta-ads (optional)
🎬 VideoScribe	video-scribe	youtube (optional)
📱 SocialScheduler AI	social-scheduler	linkedin (optional)
📦 InventoryPredict	inventory-predict	shopify

Plans & API Access

Starter

$9/agent/mo

50 executions/month
No API access
Dashboard only
Email notifications

Pro ⭐

$99/agent/mo

1,000+ executions/month
Full REST API access
Webhook events
MCP integrations

Enterprise

Custom

Unlimited executions
Dedicated endpoints
SLA + CSM
White-label option

SDKs & Quick Start

Node.js

npm install agentiv-sdk

const Agentiv = require('agentiv-sdk');
const client = new Agentiv({ apiKey: process.env.AGENTIV_API_KEY });

// Run EmailTriage
const result = await client.agents.run('email-triage', {
  input: { max_emails: 20 },
  async: false
});

console.log(result.summary);
// "Triaged 18 emails | 2 urgent | 4 archived"

Python

pip install agentiv

from agentiv import Agentiv
client = Agentiv(api_key=os.environ["AGENTIV_API_KEY"])

result = client.agents.run("email-triage", input={"max_emails": 20})
print(result.summary)

📬 Need help integrating? Email api@agentiv.cloud — Pro and Enterprise customers get dedicated integration support.

Agentiv API Reference