> For the complete documentation index, see [llms.txt](https://docs.safelink.gg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.safelink.gg/api-quick-start.md).

# API Quick Start

## Authorization

Requests are authenticated using API keys. While API keys are not a requirement for using the API, any request that doesn't include an API key will suffer lower rate limits. Please contact us via email or discord to obtain an API key.

You can provide your API key in the form of the `Authorization` header or the `token` url parameter.

```
https://api.safelink.gg/v1/check?token=YOUR_API_TOKEN
```

```
Authorization: YOUR_API_KEY
```

## Identification

While we love that you are using our API, we would like to know who you are. **If you do not have an API key, you must provide an identity to make requests.**

You can provide your identity using the `User-Agent` or `X-Identity` headers. We would like your identity to follow this schema:

```bash
$ApplicationName ($url, $version)
```

For example:

```toml
User-Agent: SafeLinkBot (https://safelink.gg, 2.0)
```

## Scanning a link

By far the simplest way to scan links is to just send a POST request with the links you would like scanned. You will receive a list of [Scan ](/reference/api-reference/scan.md#scan-structure)objects with flags and other metadata you can use to classify the links.

## Scan Links

<mark style="color:green;">`POST`</mark> `https://api.safelink.gg/v1/check`

Submits links to scan. The connection will be kept open until the links are done scanning. No polling is necessary. For more information on scans refer to the [Scan ](/reference/api-reference/scan.md#scan-structure)object

#### Request Body

| Name                                   | Type  | Description                                                                               |
| -------------------------------------- | ----- | ----------------------------------------------------------------------------------------- |
| urls<mark style="color:red;">\*</mark> | Array | An array of link strings.                                                                 |
| timeout                                | float | Time in seconds until cutting the request short and returning whatever data was gathered. |

{% tabs %}
{% tab title="200: OK Links were scanned" %}

```javascript
{
    "status": 200,
    "data": [
        {
            "url": "https://i-am-a-scam.com",
            "status": 200,
            "flags": [
                "SCAM"
            ],
            "content_type": "text/html",
            "similar_to": [],
            "scam_score": 39.0,
            "meta": {
                "title": "Scam page title",
                "description": "Meta description",
                "image": "https://i-am-a-scam.com/image.jpg",
                "type": "website",
                "site_name": "ScamSite"
            },
            "title": "ScamSite | Get scammed",
            "scan_timestamp": 1641687942,
            "scan_length": 1.622185230255127
        }
    ]
}
```

{% endtab %}

{% tab title="400: Bad Request Your link array or timeout was malformed" %}

```javascript
{
    "status": 400,
    "description": "Invalid Request",
    "message": "No URLs were provided"
}
```

{% endtab %}
{% endtabs %}

Take a look at how you might call this method:

{% tabs %}
{% tab title="curl" %}

```
curl https://api.safelink.gg/v1/check
    -H "Authorization: YOUR_API_KEY"  
    -d "urls[]=https://example.com"  
```

{% endtab %}

{% tab title="Python (aiohttp)" %}

```python
import aiohttp
import asyncio

async def main():
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.safelink.gg/v1/check",
            json={
                "urls": ["https://example.com"],
                "timeout": 60
            },
            headers={
                "Authorization": "YOUR_API_TOKEN"
            }
        ) as response:
        
            data = await response.json()
            
            print(data.get("data"))
            
if __name__ == "__main__":
    asyncio.run(main())
```

{% endtab %}

{% tab title="Python (requests)" %}

```python
import requests

def main():
    data = requests.post(
        "https://api.safelink.gg/v1/check",
        data={
            "urls": ["https://example.com"],
            "timeout": 60
        },
        headers={
            "Authorization": "YOUR_API_TOKEN"
        }
    )
    
    print(data.json().get("data"))
    
if __name__ == "__main__":
    main()
```

{% endtab %}
{% endtabs %}

## Reporting

If you detect or think that a link or domain should be flagged, but isn't, you can submit it with the proper flags here to be looked over by the SafeLink team.

## Report Links

<mark style="color:green;">`POST`</mark> `https://api.safelink.gg/v1/report`

Submits links for review.

#### Request Body

| Name                                      | Type  | Description                                                                        |
| ----------------------------------------- | ----- | ---------------------------------------------------------------------------------- |
| reports<mark style="color:red;">\*</mark> | Array | An array of [Report ](/reference/api-reference/report.md#report-structure)objects. |

{% tabs %}
{% tab title="200: OK Reports were received" %}

```javascript
{
    "status": 200,
    "data": {}
}
```

{% endtab %}

{% tab title="400: Bad Request Your Reports were malformed" %}

```javascript
{
    "status": 400,
    "description": "Invalid Request",
    "message": "No Reports were provided."
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.safelink.gg/api-quick-start.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.