Hosted Agents API Explorer | Intelligent Group

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://api.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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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.hosted-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 →

Explore the Hosted Agents API.

How authentication works.

Three endpoints. Three languages. Copy and run.

Ready to integrate?