> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skop.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Skop API Documentation

> Complete API reference for Skop - Intelligent multi-agent document discovery and extraction service

# **\[skop.dev]**

## Overview

Skop is an intelligent multi-agent document discovery and extraction service that can find and extract PDF documents from websites based on natural language prompts. The API uses advanced AI agents to navigate websites, identify relevant documents, and extract them with high accuracy.

**Base URL**: `https://api.skop.dev`\
**Version**: 1.0.0\
**Service Name**: Skop

## Authentication

All API endpoints require authentication using either:

* **Bearer Token**: Include `Authorization: Bearer <your_token>` in headers
* **API Key**: Include `X-API-Key: <your_api_key>` in headers

### Required Scopes

* `scrape:create` - Required for creating new scraping jobs
* Additional scopes may be required for other operations

<Card title="Get API Key" icon="key" href="https://www.skop.dev/dashboard">
  Visit the Skop dashboard to create an account and get your API key
</Card>

## Billing & Pricing

### Pricing Model

The API uses a results-based billing system where you only pay for pages that contain actual documents. Our LangGraph agent dynamically allocates different tiers of scraping agents:

* **Advanced Scraping Agent**: \$0.18 per page with results (high-quality extraction)
* **Standard Scraping Agent**: \$0.10 per page with results (basic extraction)

### Usage-Based Billing

The API uses a simple pay-per-use model where all users are charged based on actual results:

* **No monthly limits**: Use as much as you need
* **No plan restrictions**: All features available to all users
* **Fair pricing**: Only pay for pages that contain documents
* **Transparent costs**: Clear per-page pricing with no hidden fees

### Cost Estimation

* **Single Page**: \~\$0.10-0.18 (depending on agent tier allocated)
* **Multi-Page**: Variable based on documents found (typically \$1-5 per job)

## Quickstart

### 1. Get Your API Key

Visit [https://www.skop.dev/dashboard](https://www.skop.dev/dashboard) to create an account and get your API key.

### 2. Make Your First Request

```bash theme={null}
curl -X POST "https://api.skop.dev/scrape" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "https://example.com",
    "prompt": "Find all board meeting minutes from 2024",
    "parameters": {
      "single_page": true,
      "timeout": 1800,
      "confidence_threshold": 0.7
    }
  }'
```

### 3. Check Job Status

```bash theme={null}
curl -X GET "https://api.skop.dev/scrape/status/{job_id}" \
  -H "Authorization: Bearer <your_token>"
```

### 4. Get Results

```bash theme={null}
curl -X GET "https://api.skop.dev/scrape/results/{job_id}" \
  -H "Authorization: Bearer <your_token>"
```

## Rate Limits

* **General endpoints**: 100 requests per hour
* **Job creation**: 100 requests per hour
* **Status checks**: 300 requests per hour
* **Health checks**: 60 requests per minute

Rate limit headers are included in responses:

* `X-Rate-Limit-Remaining`: Remaining requests
* `X-Rate-Limit-Reset`: Reset timestamp

## Request & Response Format

All requests and responses use JSON format with `Content-Type: application/json`.

### Error Response Format

```json theme={null}
{
  "error": true,
  "message": "Human-readable error message",
  "status_code": 400,
  "path": "/scrape",
  "timestamp": "2024-01-15T10:00:00Z",
  "details": {
    "field": "website",
    "reason": "URL must use http or https protocol"
  }
}
```

## Common Error Codes

| HTTP Status | Error Type            | Description                            |
| ----------- | --------------------- | -------------------------------------- |
| `400`       | Bad Request           | Invalid request format or parameters   |
| `401`       | Unauthorized          | Missing or invalid authentication      |
| `402`       | Payment Required      | Insufficient credits or billing issue  |
| `403`       | Forbidden             | Access denied or feature not available |
| `404`       | Not Found             | Resource not found                     |
| `429`       | Too Many Requests     | Rate limit exceeded                    |
| `500`       | Internal Server Error | Unexpected server error                |
| `503`       | Service Unavailable   | Service temporarily unavailable        |

## Job Status Values

| Status        | Description                  |
| ------------- | ---------------------------- |
| `pending`     | Job queued, waiting to start |
| `in_progress` | Job is actively running      |
| `completed`   | Job finished successfully    |
| `failed`      | Job failed due to errors     |
| `cancelled`   | Job was cancelled by user    |