Explore the Hosted Agents API.

Interactive code snippets for every endpoint — curl, Python, and Node.js. See exactly what a request looks like, and what you get back, before you write a single line of production code.

Get API accessView full API docs
Team gathered around a screen in a bright office
Abstract render of a dark sphere with a light ring
HIPAA-compliant Bearer token auth SHA-256 audit chain REST / JSON

Authentication

How authentication works.

Every API call requires two headers: a Bearer token for authentication and an x-org-id header for tenant isolation. Both are provisioned when your account is activated.

Bearer token (Authorization header)

Your API virtual key is scoped to your organization. Pass it as Authorization: Bearer <your-virtual-key> on every request. Keys are rotatable from the dashboard at any time. Keys do not expire unless rotated or revoked.

Organization ID (x-org-id header)

All requests must include x-org-id: <your-org-id>. This header is used for tenant isolation — all agent runs, audit logs, and stored context are partitioned by org ID at the infrastructure level. It is not a secret; it is a routing signal.

Base URL

All API calls go to: https://hosted-agents.intelligentit.io/v1. The API is versioned; v1 is the current stable version. Breaking changes will be announced 90 days in advance and versioned under a new path.

Rate limits

Starter: 10 requests/second, 1,000 runs/month. Professional: 50 req/s, 10,000 runs/month. Enterprise: custom limits. Rate limit headers are returned on every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Interactive request builder

Three endpoints. Three languages. Copy and run.

Select an endpoint, pick your language, and copy the ready-to-run snippet. Replace <your-virtual-key> and <your-org-id> with the values from your dashboard.

POST https://api.agents.intelligentit.io/v1/agents/run

Trigger a new agent run. Pass the agent ID, your input payload, and optional context. Returns a run ID, the agent output, and a SHA-256 chain hash for audit trail verification.

bash — curl 
curl -X POST https://api.agents.intelligentit.io/v1/agents/run \
  -H "Authorization: Bearer <your-virtual-key>" \
  -H "x-org-id: <your-org-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "compliance-evidence-collector",
    "input": "Run SOC2 evidence collection for Q2 2026",
    "context": {
      "clientId": "client-acme-corp",
      "framework": "SOC2-TypeII"
    }
  }'import requests

# Replace with your credentials from the dashboard
VIRTUAL_KEY = "<your-virtual-key>"
ORG_ID = "<your-org-id>"

url = "https://api.agents.intelligentit.io/v1/agents/run"

headers = {
    "Authorization": f"Bearer {VIRTUAL_KEY}",
    "x-org-id": ORG_ID,
    "Content-Type": "application/json",
}

payload = {
    "agentId": "compliance-evidence-collector",
    "input": "Run SOC2 evidence collection for Q2 2026",
    "context": {
        "clientId": "client-acme-corp",
        "framework": "SOC2-TypeII",
    },
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(f"Run ID: {data['runId']}")
print(f"Chain hash: {data['chainHash']}")
print(f"Output: {data['output']}")// Node.js 18+ (native fetch) or use node-fetch for older versions
const VIRTUAL_KEY = "<your-virtual-key>";
const ORG_ID = "<your-org-id>";

const response = await fetch(
  "https://api.agents.intelligentit.io/v1/agents/run",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${VIRTUAL_KEY}`,
      "x-org-id": ORG_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agentId: "compliance-evidence-collector",
      input: "Run SOC2 evidence collection for Q2 2026",
      context: {
        clientId: "client-acme-corp",
        framework: "SOC2-TypeII",
      },
    }),
  }
);

const data = await response.json();
console.log(`Run ID: ${data.runId}`);
console.log(`Chain hash: ${data.chainHash}`);
Sample response 200 OK 
{
  "runId": "run_01HXKP3M7J9QA2NBTZ8CF4DV5W",
  "agentId": "compliance-evidence-collector",
  "status": "completed",
  "output": {
    "summary": "Evidence collection complete. 47 controls documented, 3 gaps flagged for remediation.",
    "controlsCovered": 47,
    "gapsFound": 3,
    "reportUrl": "https://vault.intelligentit.io/reports/run_01HXKP..."
  },
  "chainHash": "sha256:a3f9c2d1e8b047...",
  "prevHash": "sha256:7c21b4a9f3d05e...",
  "timestamp": "2026-05-18T14:32:07.441Z",
  "orgId": "org_acme-corp",
  "durationMs": 1842
}
GET https://api.agents.intelligentit.io/v1/agents/{id}/status

Poll the status of a specific agent run by its run ID. Use this endpoint for long-running agents or when you want to check the outcome of a run after the fact. Returns the current status, output (if complete), and the audit chain reference.

bash — curl 
curl -X GET \
  "https://api.agents.intelligentit.io/v1/agents/run_01HXKP3M7J9QA2NBTZ8CF4DV5W/status" \
  -H "Authorization: Bearer <your-virtual-key>" \
  -H "x-org-id: <your-org-id>"import requests

VIRTUAL_KEY = "<your-virtual-key>"
ORG_ID = "<your-org-id>"
RUN_ID = "run_01HXKP3M7J9QA2NBTZ8CF4DV5W"

url = f"https://api.agents.intelligentit.io/v1/agents/{RUN_ID}/status"

headers = {
    "Authorization": f"Bearer {VIRTUAL_KEY}",
    "x-org-id": ORG_ID,
}

response = requests.get(url, headers=headers)
data = response.json()

print(f"Status: {data['status']}")
if data['status'] == 'completed':
    print(f"Output: {data['output']}")const VIRTUAL_KEY = "<your-virtual-key>";
const ORG_ID = "<your-org-id>";
const RUN_ID = "run_01HXKP3M7J9QA2NBTZ8CF4DV5W";

const response = await fetch(
  `https://api.agents.intelligentit.io/v1/agents/${RUN_ID}/status`,
  {
    method: "GET",
    headers: {
      "Authorization": `Bearer ${VIRTUAL_KEY}`,
      "x-org-id": ORG_ID,
    },
  }
);

const data = await response.json();
console.log(`Status: ${data.status}`);
if (data.status === "completed") {
  console.log(`Output: ${JSON.stringify(data.output, null, 2)}`);
}
Sample response 200 OK 
{
  "runId": "run_01HXKP3M7J9QA2NBTZ8CF4DV5W",
  "agentId": "compliance-evidence-collector",
  "status": "completed",
  "createdAt": "2026-05-18T14:32:05.000Z",
  "completedAt": "2026-05-18T14:32:07.441Z",
  "output": {
    "summary": "Evidence collection complete.",
    "controlsCovered": 47,
    "gapsFound": 3
  },
  "chainHash": "sha256:a3f9c2d1e8b047...",
  "auditRef": "aud_2026Q2-run-01HXKP",
  "orgId": "org_acme-corp"
}
POST https://api.agents.intelligentit.io/v1/pilot/runs

Trigger an agent run in pilot mode — a sandboxed execution environment that uses synthetic data and does not write to your production audit chain. Use this endpoint for integration testing, CI/CD pipelines, or onboarding validation before going live.

bash — curl 
curl -X POST https://api.agents.intelligentit.io/v1/pilot/runs \
  -H "Authorization: Bearer <your-virtual-key>" \
  -H "x-org-id: <your-org-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "hipaa-risk-assessor",
    "input": "Assess data handling for EHR integration",
    "pilotConfig": {
      "syntheticData": true,
      "dryRun": true
    }
  }'import requests

VIRTUAL_KEY = "<your-virtual-key>"
ORG_ID = "<your-org-id>"

url = "https://api.agents.intelligentit.io/v1/pilot/runs"

headers = {
    "Authorization": f"Bearer {VIRTUAL_KEY}",
    "x-org-id": ORG_ID,
    "Content-Type": "application/json",
}

payload = {
    "agentId": "hipaa-risk-assessor",
    "input": "Assess data handling for EHR integration",
    "pilotConfig": {
        "syntheticData": True,
        "dryRun": True,
    },
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()

print(f"Pilot run ID: {data['runId']}")
print(f"Pilot mode: {data['pilotMode']}")
print(f"Output preview: {data['output']}")// Pilot runs — sandboxed, no writes to production audit chain
const VIRTUAL_KEY = "<your-virtual-key>";
const ORG_ID = "<your-org-id>";

const response = await fetch(
  "https://api.agents.intelligentit.io/v1/pilot/runs",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${VIRTUAL_KEY}`,
      "x-org-id": ORG_ID,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      agentId: "hipaa-risk-assessor",
      input: "Assess data handling for EHR integration",
      pilotConfig: {
        syntheticData: true,
        dryRun: true,
      },
    }),
  }
);

const data = await response.json();
console.log(`Pilot run ID: ${data.runId}`);
console.log(`Pilot mode: ${data.pilotMode}`);
Sample response 201 Created 
{
  "runId": "pilot_02JYMQ4N8K0RB3PCUZA9EG6EX1",
  "agentId": "hipaa-risk-assessor",
  "pilotMode": true,
  "syntheticData": true,
  "status": "completed",
  "output": {
    "riskScore": "low",
    "findings": 2,
    "recommendation": "EHR integration meets HIPAA baseline controls."
  },
  "note": "Pilot run — not written to production audit chain.",
  "timestamp": "2026-05-18T14:45:12.007Z",
  "orgId": "org_acme-corp"
}

Ready to integrate?

Get your virtual key and org ID provisioned in under 24 hours. We walk you through your first agent run during onboarding.

Get API access Full API reference →

Page as of 2026-05-18. API endpoints and response schemas are reference examples; final specification confirmed in onboarding. © Intelligent Group (DBA Intelligent iT) · intelligentit.io

One team

For the bold. For what's next.

Most growing firms juggle four to seven IT vendors. Our clients have one team, one number, and one invoice.

Services

What we run.

Security

24/7 security operations.

Managed SOC, Zero Trust, and audit-ready evidence for SOC 2 and HIPAA.

Managed IT

Senior engineers, no tiers.

US-based senior engineers on every ticket. Flat per-user pricing, billed annually.

AI automation

AI that does the work.

Automation handles routine IT work so your team can focus on what matters. Approved workflows cover new hires and leavers.

Build your next advantage.

Thirty minutes with a senior architect. You leave with a scope, a number, and a start date, or a straight answer that you don't need us yet.

Book 30 minutes