DocsREST API

REST API

Programmatic access to your AutoKap account. List projects, manage presets, trigger captures, and monitor usage — all via authenticated HTTP requests. Perfect for CI/CD pipelines, custom dashboards, and automated workflows.

Authentication

All REST API requests require the same CLI key you use with autokap login. Create it once from the CLI Keys page in your dashboard, then reuse it locally or in CI as a Bearer token.

Shell

curl https://autokap.app/api/v1/projects \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

There is no separate API-key system anymore. CLI keys (ak_cli_) authenticate both the CLI and REST API.

Rate limits

Requests are rate-limited per CLI key based on your billing plan. When the limit is reached, the API returns 429 Too Many Requests.

Plan	Limit
Free	10 req/min
Maker	60 req/min
Team	200 req/min

Projects

GET /api/v1/projects

List all projects available to the account linked to your CLI key.

Shell

curl https://autokap.app/api/v1/projects \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

# Response
{
  "projects": [
    {
      "id": "abc123",
      "name": "My Website",
      "url": "https://example.com",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

GET /api/v1/projects/:id

Get a single project by ID.

POST /api/v1/projects

Create a new project. Required fields: name and url. Optional: description, public_url. The favicon is auto-detected from the URL. Plan project limits apply.

Shell

curl -X POST https://autokap.app/api/v1/projects \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Website",
    "url": "https://example.com",
    "description": "Marketing site"
  }'

# Response (201)
{
  "project": {
    "id": "abc123",
    "name": "My Website",
    "url": "https://example.com",
    "description": "Marketing site",
    "icon_url": "https://example.com/favicon.ico",
    "source": "web",
    "created_at": "2026-04-07T10:30:00Z",
    "updated_at": "2026-04-07T10:30:00Z"
  }
}

Presets

GET /api/v1/presets

List presets across your projects. Use the optional project_id query parameter to filter by project.

Shell

# List all presets
curl https://autokap.app/api/v1/presets \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

# Filter by project
curl "https://autokap.app/api/v1/presets?project_id=abc123" \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

GET /api/v1/presets/:id

Get a single preset by ID, including its full configuration.

PATCH /api/v1/presets/:id

Update a preset's name, description, or configuration. Your plan's feature limits still apply.

Shell

curl -X PATCH https://autokap.app/api/v1/presets/abc123 \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated preset name",
    "description": "New description"
  }'

Captures

GET /api/v1/captures

List captures with pagination. Filter by project or preset.

Query parameters

Parameter	Description
project_id	Filter by project ID
preset_id	Filter by preset ID
limit	Number of results (default 50, max 100)
offset	Pagination offset (default 0)

Integration Endpoints

Integration endpoints provide stable public URLs for your captured assets.

Integration endpoints are automatically created and maintained when you create or update a preset. The API exposes read-only access for listing and exporting them.

GET /api/v1/endpoints

List integration endpoints. Filter by preset_id or project_id.

Shell

# List endpoints for a preset
curl "https://autokap.app/api/v1/endpoints?preset_id=abc123" \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

# List all endpoints for a project
curl "https://autokap.app/api/v1/endpoints?project_id=abc123" \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

GET /api/v1/endpoints/export

Export all endpoints for a preset as JSON or CSV. Includes the full public URL for each endpoint.

Shell

# JSON export
curl "https://autokap.app/api/v1/endpoints/export?preset_id=abc123" \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

# CSV export
curl "https://autokap.app/api/v1/endpoints/export?preset_id=abc123&format=csv" \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

Usage

GET /api/v1/usage

Get your credit usage for the current billing period.

Shell

curl https://autokap.app/api/v1/usage \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx"

# Response
{
  "plan": "maker",
  "credits_limit": 300,
  "billing_period_start": "2025-03-01T00:00:00Z",
  "usage": {
    "screenshots": 34,
    "clips": 2,
    "videos": 0,
    "preset_analyses": 3,
    "total_items": 39,
    "credits_used": 40,
    "credits_remaining": 260
  }
}

Example: CLI capture workflow

Use the CLI to run captures in your CI/CD pipeline. The CLI fetches the opcode program, executes it locally, and uploads artifacts automatically.

Shell

#!/bin/bash
# CLI capture workflow for CI/CD
PRESET_ID="your_preset_id"

# 1. Authenticate (once per environment)
npx autokap login ak_cli_xxxxxxxxxxxxxxxx

# 2. Run the capture locally
npx autokap run $PRESET_ID

# 3. Check usage via API
curl -s https://autokap.app/api/v1/usage \
  -H "Authorization: Bearer ak_cli_xxxxxxxxxxxxxxxx" | jq '.usage'

Error handling

All error responses return a JSON body with an error field describing the issue.

Status	Description
401	Invalid or missing CLI key
403	Account linked to this CLI key cannot access this resource
404	Resource not found or not accessible with this CLI key
422	Invalid request body or parameters
429	Rate limit exceeded — wait and retry
500	Internal server error — retry or contact support

Good to know

Reuse the stored key

If you already ran autokap login on a machine, reuse the stored key from ~/.autokap/config.json instead of pasting credentials into every tool call. Local agents and scripts should read that file once and keep using the same Bearer token.

One key system

The CLI and REST API now share the same ak_cli_ key format. Users only need one key to link a machine, run captures, and make programmatic requests.

Rate limit headers

Every API response includes rate limit headers: X-RateLimit-Limit (your max requests per minute), X-RateLimit-Remaining (requests left in the current window), and X-RateLimit-Reset (Unix timestamp when the window resets). When you receive a 429 response, implement exponential backoff — wait and double the delay between retries. Upgrading your plan increases your rate limit.

Webhooks (coming soon)

Webhooks will notify you in real time when a capture completes or fails. Captures are now executed locally via the CLI (autokap run), and results are uploaded to AutoKap automatically.