API Reference

v1

Build powerful integrations with the Delegir API. Manage agents, send messages, track usage, and automate your workflows programmatically.

Authentication

All API requests require an API key passed via the X-API-Key header. You can generate and manage API keys from your Dashboard Settings under the Developers tab.

Example header
X-API-Key: dlg_live_abc123def456ghi789

Important: Keep your API key secure. Never expose it in client-side code or public repositories. If you suspect a key has been compromised, revoke it immediately from the dashboard and generate a new one.

Rate Limiting

The API enforces a rate limit of 60 requests per minute per API key across all endpoints. Rate limit information is included in the response headers of every request.

Rate limit headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 54
X-RateLimit-Reset: 1710489600

If you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your integration to handle this gracefully.

Base URL

All API endpoints are relative to the following base URL:

https://delegir.com/api/v1

Response Format

All responses use a consistent JSON envelope. Successful responses include a data field. Error responses include an error field with a descriptive message.

Success response

{
  "data": {
    "id": "agt_abc123",
    "name": "My Agent"
  }
}

Error response

{
  "error": "Agent not found"
}

Common HTTP status codes

StatusDescription
200Request succeeded
400Bad request (invalid parameters or body)
401Unauthorized (missing or invalid API key)
404Resource not found
429Rate limit exceeded
500Internal server error

Endpoints

The API provides full control over your agents, conversations, and usage data.

GET/agents

Returns a list of all agents owned by the authenticated user.

Example request

cURL
curl -X GET "https://delegir.com/api/v1/agents" \
  -H "X-API-Key: your_api_key"

Example response

JSON
{
  "data": [
    {
      "id": "agt_abc123",
      "name": "Customer Support Agent",
      "status": "active",
      "safety_mode": true,
      "template": "customer-support",
      "total_runs": 1284,
      "last_active": "2026-03-15T08:30:00Z",
      "created_at": "2026-01-10T14:00:00Z"
    },
    {
      "id": "agt_def456",
      "name": "Sales Outreach Agent",
      "status": "paused",
      "safety_mode": false,
      "template": null,
      "total_runs": 320,
      "last_active": "2026-03-14T19:45:00Z",
      "created_at": "2026-02-05T09:00:00Z"
    }
  ]
}
GET/agents/:id

Returns the full configuration and metadata for a single agent.

Parameters

ParameterTypeRequiredDescription
idstringRequiredThe unique agent identifier (path parameter).

Example request

cURL
curl -X GET "https://delegir.com/api/v1/agents/agt_abc123" \
  -H "X-API-Key: your_api_key"

Example response

JSON
{
  "data": {
    "id": "agt_abc123",
    "name": "Customer Support Agent",
    "status": "active",
    "safety_mode": true,
    "template": "customer-support",
    "total_runs": 1284,
    "last_active": "2026-03-15T08:30:00Z",
    "created_at": "2026-01-10T14:00:00Z",
    "config": {
      "model": "claude-sonnet-4-5-20250514",
      "system_prompt": "You are a helpful customer support agent...",
      "temperature": 0.7,
      "max_tokens": 2048
    },
    "channels": [
      "webchat",
      "email"
    ]
  }
}
PUT/agents/:id

Updates an existing agent. Only the fields provided in the request body will be modified.

Parameters

ParameterTypeRequiredDescription
idstringRequiredThe unique agent identifier (path parameter).

Request body

JSON
{
  "name": "Updated Support Agent",
  "status": "active",
  "config": {
    "temperature": 0.5,
    "max_tokens": 4096
  }
}

Example request

cURL
curl -X PUT "https://delegir.com/api/v1/agents/agt_abc123" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Support Agent",
    "config": { "temperature": 0.5 }
  }'

Example response

JSON
{
  "data": {
    "id": "agt_abc123",
    "name": "Updated Support Agent",
    "status": "active",
    "updated_at": "2026-03-15T10:00:00Z"
  }
}
DELETE/agents/:id

Permanently deletes an agent and all associated data including run history and channel connections.

Parameters

ParameterTypeRequiredDescription
idstringRequiredThe unique agent identifier (path parameter).

Example request

cURL
curl -X DELETE "https://delegir.com/api/v1/agents/agt_abc123" \
  -H "X-API-Key: your_api_key"

Example response

JSON
{
  "data": {
    "deleted": true,
    "id": "agt_abc123"
  }
}
POST/agents/:id/chat

Sends a message to an agent and returns the AI-generated response. The agent must be in an active state.

Parameters

ParameterTypeRequiredDescription
idstringRequiredThe unique agent identifier (path parameter).

Request body

JSON
{
  "message": "How do I reset my password?"
}

Example request

cURL
curl -X POST "https://delegir.com/api/v1/agents/agt_abc123/chat" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "message": "How do I reset my password?" }'

Example response

JSON
{
  "data": {
    "response": "To reset your password, go to Settings > Security and click \"Reset Password\". You will receive a confirmation email within a few minutes.",
    "runId": "run_xyz789",
    "tokensUsed": 142
  }
}
GET/agents/:id/runs

Returns the execution history for an agent, ordered by most recent first.

Parameters

ParameterTypeRequiredDescription
idstringRequiredThe unique agent identifier (path parameter).
limitintegerOptionalNumber of runs to return (default: 20, max: 100).
offsetintegerOptionalNumber of runs to skip for pagination (default: 0).

Example request

cURL
curl -X GET "https://delegir.com/api/v1/agents/agt_abc123/runs?limit=10&offset=0" \
  -H "X-API-Key: your_api_key"

Example response

JSON
{
  "data": {
    "runs": [
      {
        "id": "run_xyz789",
        "status": "completed",
        "tokens_used": 142,
        "cost": 0.0028,
        "duration_ms": 1340,
        "created_at": "2026-03-15T08:30:00Z"
      },
      {
        "id": "run_xyz788",
        "status": "completed",
        "tokens_used": 256,
        "cost": 0.0051,
        "duration_ms": 2100,
        "created_at": "2026-03-15T08:15:00Z"
      }
    ],
    "total": 1284,
    "limit": 10,
    "offset": 0
  }
}
GET/usage

Returns API usage statistics for the current billing period, including plan limits and consumption.

Example request

cURL
curl -X GET "https://delegir.com/api/v1/usage" \
  -H "X-API-Key: your_api_key"

Example response

JSON
{
  "data": {
    "plan": "PRO",
    "runs_used": 4521,
    "runs_limit": 10000,
    "tokens_this_month": 1284350,
    "cost_this_month": 25.68,
    "billing_period_start": "2026-03-01T00:00:00Z",
    "billing_period_end": "2026-03-31T23:59:59Z"
  }
}

SDKs

Official client libraries are in development to make integrating with the Delegir API even easier.

Node.js SDK

TypeScript-first client for Node.js and edge runtimes.

Coming Soon

Python SDK

Async-ready client with Pydantic models for type safety.

Coming Soon

Support

Need help with the API? We are here to assist.

DashboardManage your agents and API keys
Emailsupport@delegir.com
StatusAPI uptime and incident reports at status.delegir.com