REST API Reference

Complete reference for the SwiftClaw REST API.

Agents

Invoke Agent

Send a message to an agent:

POST /v1/agents/{agent_id}/invoke

Request:

{
  "message": "What's the weather like?",
  "context": {
    "user_id": "user123",
    "session_id": "session456"
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "The weather is sunny with a high of 75°F.",
    "request_id": "req_abc123",
    "tokens_used": 45,
    "duration_ms": 1250
  }
}

List Agents

GET /v1/agents

Query Parameters:

limit: Number of results (default: 10, max: 100)
offset: Pagination offset
sort: Sort field (e.g., -created_at)

Response:

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "customer-support",
      "status": "running",
      "created_at": "2024-03-01T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 5,
    "has_more": false
  }
}

Get Agent

GET /v1/agents/{agent_id}

Response:

{
  "data": {
    "id": "agent_abc123",
    "name": "customer-support",
    "status": "running",
    "model": "gpt-4",
    "created_at": "2024-03-01T10:00:00Z",
    "updated_at": "2024-03-08T09:30:00Z"
  }
}

Update Agent

PATCH /v1/agents/{agent_id}

Request:

{
  "model": "gpt-4",
  "temperature": 0.7
}

Delete Agent

DELETE /v1/agents/{agent_id}

Deployments

Create Deployment

POST /v1/agents/{agent_id}/deployments

Request:

{
  "environment": "production",
  "version": "v1.2.0"
}

List Deployments

GET /v1/agents/{agent_id}/deployments

Rollback Deployment

POST /v1/agents/{agent_id}/deployments/{deployment_id}/rollback

Logs

Get Logs

GET /v1/agents/{agent_id}/logs

Query Parameters:

level: Filter by level (debug, info, warn, error)
start_time: Start timestamp
end_time: End timestamp
limit: Number of results

Response:

{
  "data": [
    {
      "timestamp": "2024-03-08T10:30:00Z",
      "level": "info",
      "message": "Agent invoked",
      "metadata": {
        "request_id": "req_abc123"
      }
    }
  ]
}

Metrics

Get Metrics

GET /v1/agents/{agent_id}/metrics

Query Parameters:

metric: Metric name (response_time, throughput, error_rate)
start_time: Start timestamp
end_time: End timestamp
granularity: Time granularity (1m, 5m, 1h, 1d)

Response:

{
  "data": {
    "metric": "response_time",
    "values": [
      {
        "timestamp": "2024-03-08T10:00:00Z",
        "value": 1250,
        "unit": "ms"
      }
    ]
  }
}

Memory

Search Memory

POST /v1/agents/{agent_id}/memory/search

Request:

{
  "query": "user preferences",
  "limit": 10
}

Clear Memory

DELETE /v1/agents/{agent_id}/memory

Webhooks

Create Webhook

POST /v1/webhooks

Request:

{
  "agent_id": "agent_abc123",
  "url": "https://yourapp.com/webhooks",
  "events": ["agent.completed", "agent.failed"]
}

List Webhooks

GET /v1/webhooks

Delete Webhook

DELETE /v1/webhooks/{webhook_id}

API Keys

Create API Key

POST /v1/keys

Request:

{
  "agent_id": "agent_abc123",
  "name": "production",
  "permissions": ["read", "write"]
}

List API Keys

GET /v1/keys

Revoke API Key

DELETE /v1/keys/{key_id}

Error Handling

Rate Limit Error

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}

Validation Error

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Validation failed",
    "details": [
      {
        "field": "message",
        "error": "Required field missing"
      }
    ]
  }
}

API Versioning: Always include version in URL path for stability.

Next Steps

REST API Reference

Complete reference for the SwiftClaw REST API.

Agents

Invoke Agent

Send a message to an agent:

POST /v1/agents/{agent_id}/invoke

Request:

{
  "message": "What's the weather like?",
  "context": {
    "user_id": "user123",
    "session_id": "session456"
  }
}

Response:

{
  "success": true,
  "data": {
    "response": "The weather is sunny with a high of 75°F.",
    "request_id": "req_abc123",
    "tokens_used": 45,
    "duration_ms": 1250
  }
}

List Agents

GET /v1/agents

Query Parameters:

limit: Number of results (default: 10, max: 100)
offset: Pagination offset
sort: Sort field (e.g., -created_at)

Response:

{
  "data": [
    {
      "id": "agent_abc123",
      "name": "customer-support",
      "status": "running",
      "created_at": "2024-03-01T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 5,
    "has_more": false
  }
}

Get Agent

GET /v1/agents/{agent_id}

Response:

{
  "data": {
    "id": "agent_abc123",
    "name": "customer-support",
    "status": "running",
    "model": "gpt-4",
    "created_at": "2024-03-01T10:00:00Z",
    "updated_at": "2024-03-08T09:30:00Z"
  }
}

Update Agent

PATCH /v1/agents/{agent_id}

Request:

{
  "model": "gpt-4",
  "temperature": 0.7
}

Delete Agent

DELETE /v1/agents/{agent_id}

Deployments

Create Deployment

POST /v1/agents/{agent_id}/deployments

Request:

{
  "environment": "production",
  "version": "v1.2.0"
}

List Deployments

GET /v1/agents/{agent_id}/deployments

Rollback Deployment

POST /v1/agents/{agent_id}/deployments/{deployment_id}/rollback

Logs

Get Logs

GET /v1/agents/{agent_id}/logs

Query Parameters:

level: Filter by level (debug, info, warn, error)
start_time: Start timestamp
end_time: End timestamp
limit: Number of results

Response:

{
  "data": [
    {
      "timestamp": "2024-03-08T10:30:00Z",
      "level": "info",
      "message": "Agent invoked",
      "metadata": {
        "request_id": "req_abc123"
      }
    }
  ]
}

Metrics

Get Metrics

GET /v1/agents/{agent_id}/metrics

Query Parameters:

metric: Metric name (response_time, throughput, error_rate)
start_time: Start timestamp
end_time: End timestamp
granularity: Time granularity (1m, 5m, 1h, 1d)

Response:

{
  "data": {
    "metric": "response_time",
    "values": [
      {
        "timestamp": "2024-03-08T10:00:00Z",
        "value": 1250,
        "unit": "ms"
      }
    ]
  }
}

Memory

Search Memory

POST /v1/agents/{agent_id}/memory/search

Request:

{
  "query": "user preferences",
  "limit": 10
}

Clear Memory

DELETE /v1/agents/{agent_id}/memory

Webhooks

Create Webhook

POST /v1/webhooks

Request:

{
  "agent_id": "agent_abc123",
  "url": "https://yourapp.com/webhooks",
  "events": ["agent.completed", "agent.failed"]
}

List Webhooks

GET /v1/webhooks

Delete Webhook

DELETE /v1/webhooks/{webhook_id}

API Keys

Create API Key

POST /v1/keys

Request:

{
  "agent_id": "agent_abc123",
  "name": "production",
  "permissions": ["read", "write"]
}

List API Keys

GET /v1/keys

Revoke API Key

DELETE /v1/keys/{key_id}

Error Handling

Rate Limit Error

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded",
    "retry_after": 60
  }
}

Validation Error

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Validation failed",
    "details": [
      {
        "field": "message",
        "error": "Required field missing"
      }
    ]
  }
}

API Versioning: Always include version in URL path for stability.

REST API

On this page

REST API

On this page