API Overview

SwiftClaw provides a REST API and SDKs for interacting with your agents.

Base URL

https://api.swiftclaw.io

Authentication

All API requests require authentication via API key:

curl https://api.swiftclaw.io/agents/my-agent/invoke \
  -H "Authorization: Bearer sk_live_abc123..."

API Versions

Current version: v1

Version is included in the URL:

https://api.swiftclaw.io/v1/agents

Rate Limits

Tier	Requests/Minute	Burst
Free	60	100
Pro	1000	2000
Enterprise	10000	20000

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1709884800

Response Format

Success Response

{
  "success": true,
  "data": {
    "message": "Hello, world!"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: message"
  }
}

Error Codes

Code	Status	Description
`invalid_request`	400	Invalid request parameters
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`rate_limited`	429	Rate limit exceeded
`server_error`	500	Internal server error

Pagination

List endpoints support pagination:

curl "https://api.swiftclaw.io/v1/agents?limit=10&offset=20" \
  -H "Authorization: Bearer sk_live_abc123..."

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "limit": 10,
    "offset": 20,
    "total": 150,
    "has_more": true
  }
}

Filtering

Filter results using query parameters:

curl "https://api.swiftclaw.io/v1/logs?level=error&limit=50" \
  -H "Authorization: Bearer sk_live_abc123..."

Sorting

Sort results using sort parameter:

curl "https://api.swiftclaw.io/v1/agents?sort=-created_at" \
  -H "Authorization: Bearer sk_live_abc123..."

Prefix with - for descending order
Default is ascending order

Idempotency

Use idempotency keys for safe retries:

curl https://api.swiftclaw.io/v1/agents/my-agent/invoke \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"message": "Hello"}'

Idempotency Window: Keys are valid for 24 hours.

Webhooks

Subscribe to events via webhooks:

curl https://api.swiftclaw.io/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123..." \
  -d '{
    "url": "https://yourapp.com/webhooks",
    "events": ["agent.completed", "agent.failed"]
  }'

SDKs

Official SDKs available:

Python: pip install swiftclaw
Node.js: npm install @swiftclaw/sdk
Go: go get github.com/swiftclaw/swiftclaw-go
Ruby: gem install swiftclaw

Next Steps

API Overview

SwiftClaw provides a REST API and SDKs for interacting with your agents.

Base URL

https://api.swiftclaw.io

Authentication

All API requests require authentication via API key:

curl https://api.swiftclaw.io/agents/my-agent/invoke \
  -H "Authorization: Bearer sk_live_abc123..."

API Versions

Current version: v1

Version is included in the URL:

https://api.swiftclaw.io/v1/agents

Rate Limits

Tier	Requests/Minute	Burst
Free	60	100
Pro	1000	2000
Enterprise	10000	20000

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1709884800

Response Format

Success Response

{
  "success": true,
  "data": {
    "message": "Hello, world!"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "invalid_request",
    "message": "Missing required parameter: message"
  }
}

Error Codes

Code	Status	Description
`invalid_request`	400	Invalid request parameters
`unauthorized`	401	Invalid or missing API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource not found
`rate_limited`	429	Rate limit exceeded
`server_error`	500	Internal server error

Pagination

List endpoints support pagination:

curl "https://api.swiftclaw.io/v1/agents?limit=10&offset=20" \
  -H "Authorization: Bearer sk_live_abc123..."

Response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "limit": 10,
    "offset": 20,
    "total": 150,
    "has_more": true
  }
}

Filtering

Filter results using query parameters:

curl "https://api.swiftclaw.io/v1/logs?level=error&limit=50" \
  -H "Authorization: Bearer sk_live_abc123..."

Sorting

Sort results using sort parameter:

curl "https://api.swiftclaw.io/v1/agents?sort=-created_at" \
  -H "Authorization: Bearer sk_live_abc123..."

Prefix with - for descending order
Default is ascending order

Idempotency

Use idempotency keys for safe retries:

curl https://api.swiftclaw.io/v1/agents/my-agent/invoke \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Idempotency-Key: unique-key-123" \
  -d '{"message": "Hello"}'

Idempotency Window: Keys are valid for 24 hours.

Webhooks

Subscribe to events via webhooks:

curl https://api.swiftclaw.io/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123..." \
  -d '{
    "url": "https://yourapp.com/webhooks",
    "events": ["agent.completed", "agent.failed"]
  }'

SDKs

Official SDKs available:

Python: pip install swiftclaw
Node.js: npm install @swiftclaw/sdk
Go: go get github.com/swiftclaw/swiftclaw-go
Ruby: gem install swiftclaw

API Overview

API Overview

Base URL

Authentication

API Versions

Rate Limits

Response Format

Success Response

Error Response

Error Codes

Filtering

Sorting

Idempotency

Webhooks

SDKs

Next Steps

On this page

API Overview

API Overview

Base URL

Authentication

API Versions

Rate Limits

Response Format

Success Response

Error Response

Error Codes

Filtering

Sorting

Idempotency

Webhooks

SDKs

Next Steps

On this page