Start a client project

curl --request POST \
  --url https://preuve.ai/api/agent/agency/analyses \
  --header 'Content-Type: application/json' \
  --header 'x-preuve-key: <api-key>' \
  --data '
{
  "clientRunId": "<string>",
  "idea": "<string>",
  "targetMarket": "<string>",
  "targetCountry": "global",
  "stage": "<string>",
  "budget": "<string>",
  "language": "en",
  "scanType": "deep",
  "publish": false
}
'

import requests

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

payload = {
    "clientRunId": "<string>",
    "idea": "<string>",
    "targetMarket": "<string>",
    "targetCountry": "global",
    "stage": "<string>",
    "budget": "<string>",
    "language": "en",
    "scanType": "deep",
    "publish": False
}
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: '<string>',
    idea: '<string>',
    targetMarket: '<string>',
    targetCountry: 'global',
    stage: '<string>',
    budget: '<string>',
    language: 'en',
    scanType: 'deep',
    publish: false
  })
};

fetch('https://preuve.ai/api/agent/agency/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/agency/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' => '<string>',
    'idea' => '<string>',
    'targetMarket' => '<string>',
    'targetCountry' => 'global',
    'stage' => '<string>',
    'budget' => '<string>',
    'language' => 'en',
    'scanType' => 'deep',
    'publish' => false
  ]),
  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/agency/analyses"

	payload := strings.NewReader("{\n  \"clientRunId\": \"<string>\",\n  \"idea\": \"<string>\",\n  \"targetMarket\": \"<string>\",\n  \"targetCountry\": \"global\",\n  \"stage\": \"<string>\",\n  \"budget\": \"<string>\",\n  \"language\": \"en\",\n  \"scanType\": \"deep\",\n  \"publish\": false\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/agency/analyses")
  .header("x-preuve-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"clientRunId\": \"<string>\",\n  \"idea\": \"<string>\",\n  \"targetMarket\": \"<string>\",\n  \"targetCountry\": \"global\",\n  \"stage\": \"<string>\",\n  \"budget\": \"<string>\",\n  \"language\": \"en\",\n  \"scanType\": \"deep\",\n  \"publish\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://preuve.ai/api/agent/agency/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\": \"<string>\",\n  \"idea\": \"<string>\",\n  \"targetMarket\": \"<string>\",\n  \"targetCountry\": \"global\",\n  \"stage\": \"<string>\",\n  \"budget\": \"<string>\",\n  \"language\": \"en\",\n  \"scanType\": \"deep\",\n  \"publish\": false\n}"

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

{
  "reportId": "<string>",
  "status": "PENDING",
  "scanType": "starter",
  "analysisTier": "<string>",
  "readyForExport": true,
  "reportUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "reused": true,
  "dispatchPending": true,
  "recovery": "<string>"
}

{
  "reportId": "<string>",
  "status": "PENDING",
  "scanType": "starter",
  "analysisTier": "<string>",
  "readyForExport": true,
  "reportUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "reused": true,
  "dispatchPending": true,
  "recovery": "<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>"
  }
}

{
  "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>"
  }
}

Agency

Start a client project

Create one deep client report against the shared Agency project quota. Never falls back to personal credits. Async: 202 on a new dispatch, 200 with reused=true when the clientRunId replays an existing report. clientRunId is scoped to the calling key; reusing one that belongs to a different workspace is 409 CLIENT_RUN_ID_CONFLICT. A response carrying dispatchPending=true means the dispatch outcome is unknown - retry the same clientRunId and arguments after 60 seconds; recovery reuses the original report and credit. 503 TRIGGER_DISPATCH_FAILED is a definite rejection: the credit was restored and that request stays failed on replay, so a new attempt needs a new clientRunId. Creating a report here does not email the client or publish a share link.

POST

api

agent

agency

analyses

Start a client project

curl --request POST \
  --url https://preuve.ai/api/agent/agency/analyses \
  --header 'Content-Type: application/json' \
  --header 'x-preuve-key: <api-key>' \
  --data '
{
  "clientRunId": "<string>",
  "idea": "<string>",
  "targetMarket": "<string>",
  "targetCountry": "global",
  "stage": "<string>",
  "budget": "<string>",
  "language": "en",
  "scanType": "deep",
  "publish": false
}
'

import requests

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

payload = {
    "clientRunId": "<string>",
    "idea": "<string>",
    "targetMarket": "<string>",
    "targetCountry": "global",
    "stage": "<string>",
    "budget": "<string>",
    "language": "en",
    "scanType": "deep",
    "publish": False
}
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: '<string>',
    idea: '<string>',
    targetMarket: '<string>',
    targetCountry: 'global',
    stage: '<string>',
    budget: '<string>',
    language: 'en',
    scanType: 'deep',
    publish: false
  })
};

fetch('https://preuve.ai/api/agent/agency/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/agency/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' => '<string>',
    'idea' => '<string>',
    'targetMarket' => '<string>',
    'targetCountry' => 'global',
    'stage' => '<string>',
    'budget' => '<string>',
    'language' => 'en',
    'scanType' => 'deep',
    'publish' => false
  ]),
  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/agency/analyses"

	payload := strings.NewReader("{\n  \"clientRunId\": \"<string>\",\n  \"idea\": \"<string>\",\n  \"targetMarket\": \"<string>\",\n  \"targetCountry\": \"global\",\n  \"stage\": \"<string>\",\n  \"budget\": \"<string>\",\n  \"language\": \"en\",\n  \"scanType\": \"deep\",\n  \"publish\": false\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/agency/analyses")
  .header("x-preuve-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"clientRunId\": \"<string>\",\n  \"idea\": \"<string>\",\n  \"targetMarket\": \"<string>\",\n  \"targetCountry\": \"global\",\n  \"stage\": \"<string>\",\n  \"budget\": \"<string>\",\n  \"language\": \"en\",\n  \"scanType\": \"deep\",\n  \"publish\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://preuve.ai/api/agent/agency/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\": \"<string>\",\n  \"idea\": \"<string>\",\n  \"targetMarket\": \"<string>\",\n  \"targetCountry\": \"global\",\n  \"stage\": \"<string>\",\n  \"budget\": \"<string>\",\n  \"language\": \"en\",\n  \"scanType\": \"deep\",\n  \"publish\": false\n}"

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

{
  "reportId": "<string>",
  "status": "PENDING",
  "scanType": "starter",
  "analysisTier": "<string>",
  "readyForExport": true,
  "reportUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "reused": true,
  "dispatchPending": true,
  "recovery": "<string>"
}

{
  "reportId": "<string>",
  "status": "PENDING",
  "scanType": "starter",
  "analysisTier": "<string>",
  "readyForExport": true,
  "reportUrl": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "pollAfterSeconds": 123,
  "reused": true,
  "dispatchPending": true,
  "recovery": "<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>"
  }
}

{
  "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

clientRunId

string

required

Idempotency key, scoped to the calling API key.

Maximum string length: 200

idea

string

required

Required string length: 40 - 50000

targetMarket

string

Maximum string length: 180

targetCountry

string

default:global

Maximum string length: 80

stage

string

Maximum string length: 80

budget

string

Maximum string length: 80

language

string

default:en

Maximum string length: 12

scanType

enum<string>

Optional and deep-only. An Agency project always spends one shared deep project credit; any other value is 400 INVALID_SCAN_TYPE.

Available options:

deep

publish

enum<boolean>

Not accepted here. Client share links are created in the Agency dashboard; publish=true is 400 INVALID_INPUT.

Available options:

false

Response

Existing report replayed via clientRunId (reused=true).

reportId

string

status

enum<string>

Available options:

PENDING,

PROCESSING,

COMPLETED,

FAILED

scanType

enum<string>

Available options:

starter,

deep

analysisTier

string

readyForExport

boolean

reportUrl

string<uri>

createdAt

string<date-time>

pollAfterSeconds

integer

Present only while the report is not terminal.

reused

boolean

Present when this clientRunId replayed an existing report.

dispatchPending

boolean

The dispatch outcome is unknown. Retry the same clientRunId and arguments after 60 seconds; recovery reuses the original report and credit. Past 23 hours the recovery text directs you to support instead of risking a duplicate job.

recovery

string

What to do next, present alongside dispatchPending.

API Reference

Endpoints

Start a client project

Authorizations

Body

Response