API Reference

Complete reference for OutScope’s REST API.

Base URL

https://api.outscope.es

Authentication

All requests require an API key in the header:

x-api-key: svc_your_key_here

Endpoints

Create Check

POST /v1/check

Create an external visibility check for a domain.

Request Body:

{
  "fqdn": "example.com",
  "ports": [80, 443],
  "paths": ["/", "/api", "/docs"],
  "vantage_point": "eu-west-1",
  "include_content_sample": false,
  "content_retention_days": 7
}

Parameters:

Field	Type	Required	Description
`fqdn`	string	Yes	Domain to check
`ports`	array	No	TCP ports (default: [80, 443])
`paths`	array	No	HTTP paths (default: [”/”])
`vantage_point`	string	No	Region to check from
`include_content_sample`	boolean	No	Capture HTTP response
`content_retention_days`	integer	No	Days to keep content (7-30)

Response (201):

{
  "id": "chk_abc123",
  "fqdn": "example.com",
  "status": "pending",
  "created_at": "2026-04-21T10:00:00Z"
}

Get Check

GET /v1/check/{id}

Retrieve check results by ID.

Response (200):

{
  "id": "chk_abc123",
  "fqdn": "example.com",
  "status": "completed",
  "analysis": {
    "reachable": true,
    "speaks_http": true,
    "analyzable": true,
    "kind": "api",
    "auth_detected": false,
    "api_doc_detected": true
  },
  "dns": {
    "a_records": ["93.184.216.34"],
    "aaaa_records": []
  },
  "ports": [
    {
      "port": 443,
      "tcp_open": true,
      "tls": {
        "valid": true,
        "expires_at": "2027-01-01T00:00:00Z"
      }
    }
  ],
  "paths": [
    {
      "path": "/",
      "status_code": 200,
      "content_type": "application/json"
    }
  ]
}

List Checks

GET /v1/checks

List all checks for your account.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Results per page (default: 30, max: 100)
`cursor`	string	Pagination cursor
`fqdn`	string	Filter by domain
`status`	string	Filter by status (pending, completed, failed)

Response (200):

{
  "data": [
    {
      "id": "chk_abc123",
      "fqdn": "example.com",
      "status": "completed",
      "created_at": "2026-04-21T10:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "cur_xyz789",
    "has_more": true
  }
}

Batch Create

POST /v1/checks/batch

Create multiple checks in one request.

Request Body:

{
  "checks": [
    {
      "fqdn": "example1.com",
      "ports": [443]
    },
    {
      "fqdn": "example2.com",
      "ports": [80, 443]
    }
  ]
}

Response (201):

{
  "created": [
    {"id": "chk_abc123", "fqdn": "example1.com"},
    {"id": "chk_abc124", "fqdn": "example2.com"}
  ],
  "stats": {
    "total": 2,
    "created": 2,
    "failed": 0
  }
}

Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
404	Not Found
429	Rate Limited - Too many requests
500	Internal Server Error

Error Responses

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid FQDN format",
    "details": {
      "field": "fqdn",
      "value": "not-a-valid-domain"
    }
  }
}

Pagination

API uses cursor-based pagination:

# First page
response = client.checks.list(limit=30)

# Next page
if response['pagination']['has_more']:
    next_page = client.checks.list(
        limit=30,
        cursor=response['pagination']['next_cursor']
    )

Webhooks

Configure webhooks to receive notifications when checks complete:

POST /v1/webhooks

{
  "url": "https://your-app.com/webhook",
  "events": ["check.completed", "check.failed"]
}