# AgentKit API Reference

> AgentKit provides AI-powered API services through a unified proxy layer.
> Access video processing (VidCap.xyz) and web scraping/SEO (ReviewWeb.site) APIs.

Base URL: https://agentkit.best

---

## Authentication

All API requests require authentication via header:
- `X-API-Key: your_api_key` (preferred)
- `Authorization: Bearer your_api_key` (alternative)

API keys: https://agentkit.best/dashboard/api-keys

---

## Error Codes

| Code | Status | Description |
|------|--------|-------------|
| MISSING_API_KEY | 401 | No API key provided |
| INVALID_API_KEY | 401 | Invalid or expired API key |
| KEY_EXPIRED | 401 | API key has expired |
| KEY_REVOKED | 401 | API key has been revoked |
| LICENSE_REQUIRED | 403 | Active license required |
| RATE_LIMIT_EXCEEDED | 429 | Too many requests |
| INVALID_PATH | 400 | Invalid proxy path format |
| UNKNOWN_SERVICE | 404 | Service not found |

---

## Rate Limits

Response headers:
- `X-RateLimit-Limit`: Max requests per hour
- `X-RateLimit-Remaining`: Requests remaining
- `X-RateLimit-Reset`: Reset timestamp (Unix)

On 429 error, response includes `retryAfter` (seconds).

---

## API Keys Management

### POST /api/keys - Create API Key

**Auth:** Session cookie (logged-in user)

**Request:**
```json
{ "name": "My API Key" }
```

**Response 201:**
```json
{
  "id": "uuid",
  "key": "ck_live_xxxx...",
  "name": "My API Key",
  "message": "Save this key securely. It will not be shown again."
}
```

**Errors:**
- 400: Name required (1-100 chars)
- 401: Unauthorized
- 403: LICENSE_REQUIRED

---

### GET /api/keys - List API Keys

**Auth:** Session cookie

**Query:** `?viewAs={userId}` (admin only)

**Response 200:**
```json
{
  "keys": [{
    "id": "uuid",
    "name": "My API Key",
    "prefix": "ck_live_",
    "last4": "ab12",
    "keyPreview": "ck_live_...ab12",
    "rateLimit": 1000,
    "isActive": true,
    "lastUsedAt": "2024-01-01T00:00:00Z",
    "usageCount": 150,
    "expiresAt": null,
    "createdAt": "2024-01-01T00:00:00Z"
  }]
}
```

---

### GET /api/keys/{id} - Get API Key Details

**Auth:** Session cookie

**Response 200:**
```json
{
  "key": {
    "id": "uuid",
    "name": "My API Key",
    "prefix": "ck_live",
    "rateLimit": 1000,
    "isActive": true,
    "rotatedAt": null,
    "gracePeriodEndsAt": null,
    "lastUsedAt": "2024-01-01T00:00:00Z",
    "usageCount": 150,
    "expiresAt": null,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}
```

**Errors:** 404: API key not found

---

### DELETE /api/keys/{id} - Delete API Key

**Auth:** Session cookie

**Response 200:**
```json
{ "success": true }
```

**Errors:** 404: API key not found

---

### POST /api/keys/{id}/rotate - Rotate API Key

**Auth:** Session cookie

Generates new key with 24h grace period for old key.

**Response 200:**
```json
{
  "key": "ck_live_new_xxxx...",
  "message": "New key created. Old key valid for 24 hours (grace period).",
  "gracePeriodHours": 24
}
```

**Errors:**
- 400: Cannot rotate inactive key
- 404: API key not found

---

### POST /api/keys/{id}/revoke - Revoke API Key

**Auth:** Session cookie

Immediately invalidates key (no grace period).

**Response 200:**
```json
{
  "success": true,
  "message": "API key revoked immediately. No grace period."
}
```

**Errors:** 404: API key not found

---

### GET /api/keys/{id}/usage - Get Usage Statistics

**Auth:** Session cookie

**Query:** `?days=7` (1-30, default 7)

**Response 200:**
```json
{
  "dailyUsage": [{ "date": "2024-01-01", "count": 50 }],
  "totalUsageCount": 500,
  "rateLimit": {
    "limit": 1000,
    "used": 25,
    "remaining": 975,
    "windowHours": 1
  }
}
```

---

### POST /api/keys/validate - Validate API Key

**Headers:** `X-API-Key` or `Authorization: Bearer`

**Response 200:**
```json
{
  "valid": true,
  "userId": "uuid",
  "rateLimit": 1000,
  "isActive": true
}
```

**Response 401:**
```json
{ "valid": false, "error": "Invalid or expired API key" }
```

---

## Referral APIs

### GET /api/referrals/referees - List Referral Conversion Rows

**Auth:** `X-API-Key` or `Authorization: Bearer` (session cookie also supported for dashboard use)

Returns the current user's owner-scoped referral conversion rows. Each item represents one commission/conversion row, not one deduplicated person.

**Query:**
- `status`: all | pending | approved | paid | cancelled (default: all)
- `limit`: 1-100 (default: 20)
- `offset`: 0-5000 (default: 0)
- `orderRef`: exact 8-character `order.displayId`, for example ff95c7f6
- `sort`: createdAt | amount | status (default: createdAt)
- `order`: asc | desc (default: desc)

**Response 200:**
```json
{
  "data": [{
    "commissionId": "uuid",
    "status": "pending",
    "amount": 990,
    "currency": "USD",
    "createdAt": "2026-05-01T00:00:00.000Z",
    "approvedAt": null,
    "paidAt": null,
    "order": {
      "displayId": "ff95c7f6",
      "productType": "engineer_kit",
      "status": "completed"
    },
    "referee": {
      "name": "Buyer",
      "avatarUrl": null,
      "emailMasked": "b****@example.com"
    }
  }],
  "pagination": { "limit": 20, "offset": 0, "total": 1, "hasMore": false },
  "filters": { "status": "all", "sort": "createdAt", "order": "desc", "orderRef": "ff95c7f6" }
}
```

**Privacy:** Does not return raw email, internal referee user id, full order id, payment metadata, bank details, or admin `viewAs` data.

**Errors:** 400 invalid query, 401 unauthorized, 403 ineligible, 429 rate limited, 500 server/config error.

---

## Proxy Services

Format: `/api/proxy/{service}/{path}`

**Headers:** `X-API-Key` or `Authorization: Bearer`

**Services:** vidcap, reviewweb

### GET /api/proxy/services - List Services

**Response 200:**
```json
{
  "services": [{
    "id": "vidcap",
    "name": "VidCap.xyz",
    "baseUrl": "https://vidcap.xyz/api",
    "timeout": 120000,
    "allowedPaths": ["/v1/..."]
  }],
  "usage": {
    "format": "/api/proxy/{service}/{path}",
    "example": "/api/proxy/vidcap/v1/extract",
    "headers": { "required": "x-api-key or Authorization: Bearer {key}" }
  }
}
```

---

## VidCap - Video Processing

AI-powered YouTube video processing.

### GET /api/proxy/vidcap/v1/healthz
Health check. Returns service status.

### GET /api/proxy/vidcap/v1/ai/models
List available AI models.

### GET /api/proxy/vidcap/v1/video/{videoId}
Get video by internal ID.

### GET /api/proxy/vidcap/v1/youtube/info
**Query:** `url` (YouTube URL)
Returns video metadata (title, duration, thumbnail, etc).

### GET /api/proxy/vidcap/v1/youtube/media
**Query:** `url`
Returns available formats (video/audio quality options).

### GET /api/proxy/vidcap/v1/youtube/download
**Query:** `url`, `format` (optional)
Returns download URL.

### GET /api/proxy/vidcap/v1/youtube/caption
**Query:** `url`, `lang` (optional, default: en)
Returns video captions/transcripts.

### GET /api/proxy/vidcap/v1/youtube/summary
**Query:** `url`
Returns AI-generated video summary.

### POST /api/proxy/vidcap/v1/youtube/summary-custom
**Body:**
```json
{
  "url": "https://youtube.com/watch?v=...",
  "prompt": "Summarize key points",
  "model": "gemini-1.5-flash"
}
```
Returns custom AI summary based on prompt.

### GET /api/proxy/vidcap/v1/youtube/article
**Query:** `url`
Converts video to article format.

### GET /api/proxy/vidcap/v1/youtube/screenshot
**Query:** `url`, `timestamp` (seconds, optional)
Returns screenshot at timestamp.

### GET /api/proxy/vidcap/v1/youtube/screenshot-multiple
**Query:** `url`, `count` (optional)
Returns multiple screenshots at intervals.

### GET /api/proxy/vidcap/v1/youtube/comments
**Query:** `url`, `limit` (optional)
Returns video comments.

### GET /api/proxy/vidcap/v1/youtube/search
**Query:** `q` (search query), `limit` (optional)
Search YouTube videos.

---

## ReviewWeb - Web Scraping & SEO

Web scraping, extraction, and SEO analysis.

### GET /api/proxy/reviewweb/v1/healthz
Health check.

### GET /api/proxy/reviewweb/v1/profile
Get account profile and usage.

### POST /api/proxy/reviewweb/v1/screenshot
**Body:**
```json
{
  "url": "https://example.com",
  "fullPage": false,
  "width": 1920,
  "height": 1080
}
```
Take webpage screenshot.

### GET /api/proxy/reviewweb/v1/screenshot/{id}
Get screenshot by ID.

### POST /api/proxy/reviewweb/v1/review
**Body:**
```json
{ "url": "https://example.com" }
```
Create comprehensive website review.

### GET /api/proxy/reviewweb/v1/review/{reviewId}
Get review by ID.

### POST /api/proxy/reviewweb/v1/scrape
**Body:**
```json
{
  "url": "https://example.com",
  "waitFor": "networkidle",
  "timeout": 30000
}
```
Scrape single URL (returns HTML).

### POST /api/proxy/reviewweb/v1/scrape/urls
**Body:**
```json
{ "urls": ["https://example.com", "..."] }
```
Scrape multiple URLs.

### POST /api/proxy/reviewweb/v1/scrape/links-map
**Body:**
```json
{ "url": "https://example.com", "depth": 1 }
```
Get links map from page.

### POST /api/proxy/reviewweb/v1/extract
**Body:**
```json
{ "url": "https://example.com" }
```
Extract main content (title, text, images).

### POST /api/proxy/reviewweb/v1/extract/urls
**Body:**
```json
{ "urls": ["https://example.com", "..."] }
```
Extract from multiple URLs.

### POST /api/proxy/reviewweb/v1/convert/markdown
**Body:**
```json
{ "url": "https://example.com" }
```
Convert webpage to markdown.

### POST /api/proxy/reviewweb/v1/convert/markdown/urls
**Body:**
```json
{ "urls": ["https://example.com", "..."] }
```
Convert multiple URLs to markdown.

### POST /api/proxy/reviewweb/v1/summarize/url
**Body:**
```json
{
  "url": "https://example.com",
  "model": "gemini-1.5-flash"
}
```
AI-summarize single URL.

### POST /api/proxy/reviewweb/v1/summarize/website
**Body:**
```json
{
  "url": "https://example.com",
  "depth": 2,
  "model": "gemini-1.5-flash"
}
```
Summarize entire website.

### POST /api/proxy/reviewweb/v1/summarize/urls
**Body:**
```json
{ "urls": ["..."], "model": "gemini-1.5-flash" }
```
Summarize multiple URLs.

### GET /api/proxy/reviewweb/v1/ai/models
List available AI models.

### POST /api/proxy/reviewweb/v1/url/is-alive
**Body:**
```json
{ "url": "https://example.com" }
```
Check if URL is accessible.

### POST /api/proxy/reviewweb/v1/url/get-url-after-redirects
**Body:**
```json
{ "url": "https://bit.ly/xxx" }
```
Get final URL after redirects.

### POST /api/proxy/reviewweb/v1/seo-insights/backlinks
**Body:**
```json
{ "domain": "example.com" }
```
Analyze domain backlinks.

### POST /api/proxy/reviewweb/v1/seo-insights/keyword-ideas
**Body:**
```json
{ "keyword": "ai tools", "country": "US" }
```
Generate keyword ideas.

### POST /api/proxy/reviewweb/v1/seo-insights/keyword-difficulty
**Body:**
```json
{ "keyword": "ai tools", "country": "US" }
```
Check keyword difficulty score.

### POST /api/proxy/reviewweb/v1/seo-insights/traffic
**Body:**
```json
{ "domain": "example.com" }
```
Analyze domain traffic metrics.

---

## Support

- Docs: https://agentkit.best/api-docs
- Email: support@agentkit.best
- Website: https://agentkit.best