Start an analysis

curl --request POST \
  --url https://preuve.ai/api/agent/analyses \
  --header 'Content-Type: application/json' \
  --header 'x-preuve-key: <api-key>' \
  --data '
{
  "clientRunId": "my-run-001",
  "scanType": "starter",
  "idea": "A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.",
  "targetMarket": "Independent coffee shops",
  "targetCountry": "US",
  "enrichmentMode": "core",
  "publish": true
}
'

import requests

url = "https://preuve.ai/api/agent/analyses"

payload = {
    "clientRunId": "my-run-001",
    "scanType": "starter",
    "idea": "A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.",
    "targetMarket": "Independent coffee shops",
    "targetCountry": "US",
    "enrichmentMode": "core",
    "publish": True
}
headers = {
    "x-preuve-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-preuve-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    clientRunId: 'my-run-001',
    scanType: 'starter',
    idea: 'A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.',
    targetMarket: 'Independent coffee shops',
    targetCountry: 'US',
    enrichmentMode: 'core',
    publish: true
  })
};

fetch('https://preuve.ai/api/agent/analyses', 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://preuve.ai/api/agent/analyses",
  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([
    'clientRunId' => 'my-run-001',
    'scanType' => 'starter',
    'idea' => 'A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.',
    'targetMarket' => 'Independent coffee shops',
    'targetCountry' => 'US',
    'enrichmentMode' => 'core',
    'publish' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-preuve-key: <api-key>"
  ],
]);

$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://preuve.ai/api/agent/analyses"

	payload := strings.NewReader("{\n  \"clientRunId\": \"my-run-001\",\n  \"scanType\": \"starter\",\n  \"idea\": \"A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.\",\n  \"targetMarket\": \"Independent coffee shops\",\n  \"targetCountry\": \"US\",\n  \"enrichmentMode\": \"core\",\n  \"publish\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-preuve-key", "<api-key>")
	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://preuve.ai/api/agent/analyses")
  .header("x-preuve-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"clientRunId\": \"my-run-001\",\n  \"scanType\": \"starter\",\n  \"idea\": \"A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.\",\n  \"targetMarket\": \"Independent coffee shops\",\n  \"targetCountry\": \"US\",\n  \"enrichmentMode\": \"core\",\n  \"publish\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://preuve.ai/api/agent/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-preuve-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"clientRunId\": \"my-run-001\",\n  \"scanType\": \"starter\",\n  \"idea\": \"A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.\",\n  \"targetMarket\": \"Independent coffee shops\",\n  \"targetCountry\": \"US\",\n  \"enrichmentMode\": \"core\",\n  \"publish\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reportId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRunId": "<string>",
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scanType": "starter",
  "enrichmentMode": "core",
  "publish": true,
  "reportType": "quick",
  "analysisTier": "basic",
  "status": "PENDING",
  "progressStep": "<string>",
  "errorCode": "<string>",
  "errorMessage": "<string>",
  "resetAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "pollHint": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "readyForExport": true,
  "exportable": true,
  "exportBlockedCode": "REPORT_NOT_FROM_AGENT_RUN",
  "exportBlockedHint": "<string>",
  "enrichment": {
    "mode": "core",
    "status": "not_required",
    "required": [
      "<string>"
    ],
    "completed": [
      "<string>"
    ],
    "missing": [
      "<string>"
    ],
    "processing": [
      "<string>"
    ],
    "failed": [
      "<string>"
    ],
    "sections": {}
  },
  "modules": {
    "proofOfDemand": {
      "status": "not_generated"
    },
    "founderFit": {
      "status": "not_generated"
    },
    "playbook": {
      "status": "not_generated"
    },
    "trends": {
      "status": "not_generated"
    },
    "community": {
      "status": "not_generated"
    }
  },
  "reportUrl": "<string>",
  "shareUrl": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

POST

api

agent

analyses

Start an analysis

curl --request POST \
  --url https://preuve.ai/api/agent/analyses \
  --header 'Content-Type: application/json' \
  --header 'x-preuve-key: <api-key>' \
  --data '
{
  "clientRunId": "my-run-001",
  "scanType": "starter",
  "idea": "A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.",
  "targetMarket": "Independent coffee shops",
  "targetCountry": "US",
  "enrichmentMode": "core",
  "publish": true
}
'

import requests

url = "https://preuve.ai/api/agent/analyses"

payload = {
    "clientRunId": "my-run-001",
    "scanType": "starter",
    "idea": "A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.",
    "targetMarket": "Independent coffee shops",
    "targetCountry": "US",
    "enrichmentMode": "core",
    "publish": True
}
headers = {
    "x-preuve-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-preuve-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    clientRunId: 'my-run-001',
    scanType: 'starter',
    idea: 'A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.',
    targetMarket: 'Independent coffee shops',
    targetCountry: 'US',
    enrichmentMode: 'core',
    publish: true
  })
};

fetch('https://preuve.ai/api/agent/analyses', 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://preuve.ai/api/agent/analyses",
  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([
    'clientRunId' => 'my-run-001',
    'scanType' => 'starter',
    'idea' => 'A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.',
    'targetMarket' => 'Independent coffee shops',
    'targetCountry' => 'US',
    'enrichmentMode' => 'core',
    'publish' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-preuve-key: <api-key>"
  ],
]);

$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://preuve.ai/api/agent/analyses"

	payload := strings.NewReader("{\n  \"clientRunId\": \"my-run-001\",\n  \"scanType\": \"starter\",\n  \"idea\": \"A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.\",\n  \"targetMarket\": \"Independent coffee shops\",\n  \"targetCountry\": \"US\",\n  \"enrichmentMode\": \"core\",\n  \"publish\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-preuve-key", "<api-key>")
	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://preuve.ai/api/agent/analyses")
  .header("x-preuve-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"clientRunId\": \"my-run-001\",\n  \"scanType\": \"starter\",\n  \"idea\": \"A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.\",\n  \"targetMarket\": \"Independent coffee shops\",\n  \"targetCountry\": \"US\",\n  \"enrichmentMode\": \"core\",\n  \"publish\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://preuve.ai/api/agent/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-preuve-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"clientRunId\": \"my-run-001\",\n  \"scanType\": \"starter\",\n  \"idea\": \"A scheduling assistant that helps independent coffee shops coordinate weekly local supplier orders with lower waste.\",\n  \"targetMarket\": \"Independent coffee shops\",\n  \"targetCountry\": \"US\",\n  \"enrichmentMode\": \"core\",\n  \"publish\": true\n}"

response = http.request(request)
puts response.read_body

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reportId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "clientRunId": "<string>",
  "batchId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "scanType": "starter",
  "enrichmentMode": "core",
  "publish": true,
  "reportType": "quick",
  "analysisTier": "basic",
  "status": "PENDING",
  "progressStep": "<string>",
  "errorCode": "<string>",
  "errorMessage": "<string>",
  "resetAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "pollHint": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "readyForExport": true,
  "exportable": true,
  "exportBlockedCode": "REPORT_NOT_FROM_AGENT_RUN",
  "exportBlockedHint": "<string>",
  "enrichment": {
    "mode": "core",
    "status": "not_required",
    "required": [
      "<string>"
    ],
    "completed": [
      "<string>"
    ],
    "missing": [
      "<string>"
    ],
    "processing": [
      "<string>"
    ],
    "failed": [
      "<string>"
    ],
    "sections": {}
  },
  "modules": {
    "proofOfDemand": {
      "status": "not_generated"
    },
    "founderFit": {
      "status": "not_generated"
    },
    "playbook": {
      "status": "not_generated"
    },
    "trends": {
      "status": "not_generated"
    },
    "community": {
      "status": "not_generated"
    }
  },
  "reportUrl": "<string>",
  "shareUrl": "<string>"
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

{
  "error": "<string>",
  "code": "<string>",
  "details": {},
  "limit": 123,
  "remaining": 123,
  "resetAt": "2023-11-07T05:31:56Z",
  "tokenBalance": 123,
  "scansUsed": 123,
  "scansRemaining": 123,
  "limitType": "<string>",
  "upgradeHint": "<string>",
  "paused": true,
  "upsell": {
    "offer": "founder_report",
    "price": "<string>",
    "guarantee": "<string>",
    "url": "<string>",
    "locked": [
      "<string>"
    ],
    "note": "<string>"
  }
}

Authorizations

x-preuve-key

string

header

required

Your API key (prv_...), sent as-is. It is the only credential the API needs - see the Authentication guide.

Body

application/json

Every field an analysis request can carry. Nothing is required here - CreateAnalysisRequest and BatchAnalysisItem each add their own required list, because a batch item may inherit scanType from the batch while a standalone create must state it.

clientRunId

string

required

Caller-chosen idempotency id. Reusing it replays the existing run.

scanType

enum<string>

required

"starter" costs nothing; "deep" runs the full paid analysis and consumes account quota. "free" is accepted as a legacy alias of "starter".

Available options:

starter,

deep

idea

string

required

The startup idea, in plain language.

targetMarket

string

targetCountry

string

ISO country code, e.g. "US" or "FR".

title

string

stage

string

Where the founder is today. Canonical values: idea, validation, mvp, launched, growth, scaling (free text tolerated). Optional here, but the MCP tools require it for deep scans; it feeds the feasibility analysis.

budget

string

Budget available to pursue the idea. Canonical values: bootstrap (no outside money), 10k, 50k, 100k, 100kPlus (over $100k), 1mPlus (over $1M); free text tolerated. Optional here, but the MCP tools require it for deep scans; it feeds the feasibility analysis.

language

string

default:en

enrichmentMode

enum<string>

default:core

"core" also generates the export-required sections; "none" returns the raw completion only.

Available options:

core,

none

publish

boolean

When true, creates a public share URL for the report.

Response

Run created (or replayed via clientRunId).

string<uuid>

reportId

string<uuid> | null

Null until the report row is attached, which is why a run that failed before dispatch is retryable under the same clientRunId.

clientRunId

string | null

The caller-chosen id from create. Null when the analysis is a dashboard-created report resolved by its report id: no run row exists, so there is no clientRunId to replay.

batchId

string<uuid> | null

The batch this run belongs to, or null for a standalone run.

scanType

enum<string>

Your request type. Reliable from creation, even while PROCESSING.

Available options:

starter,

deep

enrichmentMode

enum<string>

Available options:

core,

none

publish

boolean

reportType

enum<string> | null

Available options:

quick,

deep_dive,

null

analysisTier

enum<string> | null

Derived from the report. Deep runs read "basic" until deep sections land.

Available options:

basic,

advanced,

null

status

enum<string>

Available options:

PENDING,

PROCESSING,

COMPLETED,

FAILED

progressStep

string | null

Free-text pipeline stage while PROCESSING.

errorCode

string | null

Set on a FAILED run. Two internal markers are deliberately rewritten before they leave: an ambiguous dispatch reports TRIGGER_DISPATCH_FAILED and an ambiguous claim refund reports REPORT_CREATE_FAILED.

errorMessage

string | null

resetAt

string<date-time>

Present only on a batch item refused by the rolling daily cap; absent, not null, on every other run.

pollAfterSeconds

integer

Present only while polling is still useful. Pace by this rather than by a fixed interval.

pollHint

string

Present alongside pollAfterSeconds.

createdAt

string<date-time>

updatedAt

string<date-time>

readyForExport

boolean

Whether GET /export will serve this analysis now. Always false for a report created on the preuve.ai dashboard, whatever state the report is in, because that export answers 403 REPORT_NOT_FROM_AGENT_RUN. Branch on exportable first.

exportable

boolean

Present, and false, only on a report created on the preuve.ai dashboard. Absent means the ordinary contract applies and readyForExport is the gate. When it is false, no amount of polling or enriching changes it.

exportBlockedCode

enum<string>

Present alongside exportable, naming the refusal.

Available options:

REPORT_NOT_FROM_AGENT_RUN

exportBlockedHint

string

Present alongside exportable. Relayable prose.

enrichment

object

Progress of the core export sections. The four name arrays partition required, so a poller decides what to do next by reading them rather than by parsing status: anything in processing means keep polling, anything in failed means call enrich again, and missing with nothing processing means enrichment was never started for it.

Show child attributes

modules

object | null

Per-module statuses. Deep reports only; null on free runs.

Show child attributes

reportUrl

string<uri> | null

Null until the report row exists.

API Reference

Endpoints

Start an analysis

Authorizations

Body

Response