Start the website scan
Creates the setup draft for a domain (default: the verified email’s) and scans it in the background. Answers 202 with the draft at once; poll GET /api/v2/onboarding/draft. 400 INVALID_DOMAIN for a domain that cannot be parsed; 429 RATE_LIMITED past 5 scans per user per day.
curl --request POST \
--url https://app.octolens.com/api/v2/onboarding/scan \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domain": "acme.dev",
"force": true
}
'import requests
url = "https://app.octolens.com/api/v2/onboarding/scan"
payload = {
"domain": "acme.dev",
"force": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({domain: 'acme.dev', force: true})
};
fetch('https://app.octolens.com/api/v2/onboarding/scan', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.octolens.com/api/v2/onboarding/scan",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'domain' => 'acme.dev',
'force' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.octolens.com/api/v2/onboarding/scan"
payload := strings.NewReader("{\n \"domain\": \"acme.dev\",\n \"force\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.octolens.com/api/v2/onboarding/scan")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"domain\": \"acme.dev\",\n \"force\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.octolens.com/api/v2/onboarding/scan")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"domain\": \"acme.dev\",\n \"force\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "draft_k3v9x0q2m1",
"domain": "<string>",
"status": "scanning",
"profile": {
"name": "<string>",
"description": "<string>",
"industry": "<string>",
"website": "<string>",
"domainVariants": [
"<string>"
],
"productAreas": [
{
"label": "<string>",
"path": "<string>"
}
],
"ownAccounts": [
{
"platform": "x",
"handle": "<string>"
}
],
"founderHandles": [
"<string>"
],
"protectedVocabulary": [
"<string>"
],
"competitors": [
{
"name": "<string>",
"why": "<string>",
"domain": "<string>"
}
],
"relevanceContext": "<string>",
"productUseCases": [
"<string>"
],
"companyMoat": "<string>"
},
"degraded": [
{
"code": "enrichment_failed",
"message": "<string>"
}
],
"scanSteps": [
{
"step": "cache",
"status": "pending",
"line": "<string>",
"ms": 4503599627370495
}
],
"cached": true,
"reused": true,
"skillVersion": "<string>",
"appliedOrganizationId": "<string>",
"expiresAt": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>"
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}Authorizations
Clerk API key. Create one in Settings → API Keys. Pass as Authorization: Bearer <key>. Keys carry a scope — read, write (implies read) or admin (implies write) — chosen when the key is minted. Each operation's security requirement (and its x-required-scope extension) names the minimum scope it needs; request the least-privileged key that covers the operations you call.
Body
Response
202 response
draft_… id.
"draft_k3v9x0q2m1"
Where the draft is in the setup engine. The scan moves scanning → scanned (or failed).
scanning, scanned, proposing, measuring, sampling, ready, needs_narrowing, failed, applied What the domain scan learned about the company. Every field the wizard renders is editable.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
True when the profile came from the domain cache.
True when an existing draft (same owner + domain, < 24 h) was returned.
ISO-8601.
Was this page helpful?
curl --request POST \
--url https://app.octolens.com/api/v2/onboarding/scan \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"domain": "acme.dev",
"force": true
}
'import requests
url = "https://app.octolens.com/api/v2/onboarding/scan"
payload = {
"domain": "acme.dev",
"force": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({domain: 'acme.dev', force: true})
};
fetch('https://app.octolens.com/api/v2/onboarding/scan', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://app.octolens.com/api/v2/onboarding/scan",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'domain' => 'acme.dev',
'force' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://app.octolens.com/api/v2/onboarding/scan"
payload := strings.NewReader("{\n \"domain\": \"acme.dev\",\n \"force\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://app.octolens.com/api/v2/onboarding/scan")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"domain\": \"acme.dev\",\n \"force\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.octolens.com/api/v2/onboarding/scan")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"domain\": \"acme.dev\",\n \"force\": true\n}"
response = http.request(request)
puts response.read_body{
"id": "draft_k3v9x0q2m1",
"domain": "<string>",
"status": "scanning",
"profile": {
"name": "<string>",
"description": "<string>",
"industry": "<string>",
"website": "<string>",
"domainVariants": [
"<string>"
],
"productAreas": [
{
"label": "<string>",
"path": "<string>"
}
],
"ownAccounts": [
{
"platform": "x",
"handle": "<string>"
}
],
"founderHandles": [
"<string>"
],
"protectedVocabulary": [
"<string>"
],
"competitors": [
{
"name": "<string>",
"why": "<string>",
"domain": "<string>"
}
],
"relevanceContext": "<string>",
"productUseCases": [
"<string>"
],
"companyMoat": "<string>"
},
"degraded": [
{
"code": "enrichment_failed",
"message": "<string>"
}
],
"scanSteps": [
{
"step": "cache",
"status": "pending",
"line": "<string>",
"ms": 4503599627370495
}
],
"cached": true,
"reused": true,
"skillVersion": "<string>",
"appliedOrganizationId": "<string>",
"expiresAt": "<string>",
"createdAt": "<string>",
"updatedAt": "<string>"
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}{
"error": {
"code": "NOT_FOUND",
"message": "Resource not found",
"status": 404,
"details": [
"<unknown>"
],
"upgradeUrl": "https://app.octolens.com/me/upgrade?src=agents",
"upgradeCommand": "octolens upgrade"
}
}