curl --request POST \
--url https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"dryRun": true
}'import requests
url = "https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle"
payload = { "dryRun": 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({dryRun: true})
};
fetch('https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle', 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.searchable.com/api/mcp/pitches/{pitchId}/lifecycle",
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([
'dryRun' => 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.searchable.com/api/mcp/pitches/{pitchId}/lifecycle"
payload := strings.NewReader("{\n \"dryRun\": 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.searchable.com/api/mcp/pitches/{pitchId}/lifecycle")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"dryRun\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle")
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 \"dryRun\": true\n}"
response = http.request(request)
puts response.read_body{
"pitch": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"domain": "<string>",
"workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "active",
"createdAt": "2023-11-07T05:31:56Z",
"expiresAt": "2023-11-07T05:31:56Z",
"daysLeft": 123,
"extended": true,
"refreshes": {
"limit": 123,
"used": 123,
"remaining": 123
},
"hiddenFromPicker": true,
"trackedPromptCount": 123,
"canReactivate": true,
"canExtend": true
},
"success": true,
"message": "<string>",
"joinedExistingRun": true
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}Change a pitch
Act on a pitch as the app’s pitch controls do. action is one of: reactivate brings back a paused or expired pitch (with days left it resumes its remaining time; with none it uses the pitch’s one 7-day extension, and a pitch with no days left whose extension is used cannot be reactivated, so convert it); extend adds 7 days to an active pitch, using its one extension, only in its last 48 hours; refresh runs a new visibility report for an active pitch, using one of its 5 manual refreshes (while a report is already running for it, its first report or one an earlier refresh or an unfiltered Run report started, the refresh joins that report and uses none); convert turns the pitch into a client project with every feature unlocked, its prompts moving onto the plan’s prompt allowance, and cannot be undone; decline pauses an active pitch, keeping its data, while its expiry keeps running; hide and unhide take a paused or expired pitch out of the project picker, or put it back. The API has no confirm step: the request is the decision, so every action acts at once, including a reactivate that uses the extension, an extend, a refresh and a convert. dryRun: true is the way to look first: it runs every check the action runs and answers the preview with 200, changing nothing. The roles follow the app’s pitch routes: extending and refreshing need write access to the pitch; converting, declining, hiding and unhiding need manage access to it; reactivating needs the right to create projects in its workspace (403 forbidden otherwise). Requires a connection minted with the project:manage capability (not the bare write scope); a project-bound key reaches only its own pitch. Supports Idempotency-Key replay, scoped to the pitch: a replayed refresh uses one refresh, a reused key with a different body returns 409 idempotency_conflict (a dryRun answer is stored too, so acting after a preview takes a new key), and the same key on another pitch is a new request. Refusals: 403 plan_upgrade_required (with requiresUpgrade: true) when the workspace’s plan has no pitches, 403 pitch_allowance_used when a reactivated pitch’s prompts no longer fit the pitch allowance, 403 quota_exceeded (with quotaConflict) for a convert the plan’s prompt allowance cannot take, a dryRun included, 409 cannot_reactivate, already_extended, extend_not_available_yet (with opensAt), no_refreshes_left, pitch_not_active, pitch_still_active, already_converted and not_a_pitch, 409 duplicate_domain for a reactivation while another project or pitch holds the domain (it names no holder), and 503 refresh_failed when the report could not start, in which case no refresh is used. 403 security_policy_denied when the pitch’s workspace has API access disabled or its IP allowlist refuses the request (a caller who is no member of that workspace gets 404 not_found instead).
curl --request POST \
--url https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"dryRun": true
}'import requests
url = "https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle"
payload = { "dryRun": 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({dryRun: true})
};
fetch('https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle', 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.searchable.com/api/mcp/pitches/{pitchId}/lifecycle",
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([
'dryRun' => 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.searchable.com/api/mcp/pitches/{pitchId}/lifecycle"
payload := strings.NewReader("{\n \"dryRun\": 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.searchable.com/api/mcp/pitches/{pitchId}/lifecycle")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"dryRun\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://app.searchable.com/api/mcp/pitches/{pitchId}/lifecycle")
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 \"dryRun\": true\n}"
response = http.request(request)
puts response.read_body{
"pitch": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"name": "<string>",
"domain": "<string>",
"workspaceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "active",
"createdAt": "2023-11-07T05:31:56Z",
"expiresAt": "2023-11-07T05:31:56Z",
"daysLeft": 123,
"extended": true,
"refreshes": {
"limit": 123,
"used": 123,
"remaining": 123
},
"hiddenFromPicker": true,
"trackedPromptCount": 123,
"canReactivate": true,
"canExtend": true
},
"success": true,
"message": "<string>",
"joinedExistingRun": true
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}{
"type": "<string>",
"title": "<string>",
"status": 123,
"code": "unauthorized",
"error": "<string>",
"message": "<string>",
"howToFix": "<string>",
"requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"requiresUpgrade": true,
"retryable": true,
"timeout": true,
"quotaExceeded": true,
"current": 123,
"limit": 123,
"bulkLimitExceeded": true,
"requested": 123,
"maxAllowed": 123,
"details": {
"formErrors": [
"<string>"
],
"fieldErrors": {}
},
"opensAt": "2023-11-07T05:31:56Z",
"existing": {},
"quotaConflict": {
"current": 123,
"pitchPromptCount": 123,
"limit": 123,
"shortfall": 123
}
}Authorizations
A Searchable API key, created under Manage Account → Integrations → API Keys. Send as Authorization: Bearer sea_xxxxx. Every key carries one or more scopes (read, write, admin) and may optionally be bound to a single project — see Getting started.
Headers
Optional client-generated key (e.g. a UUID). Retrying with the same key within 24h replays the original stored response (X-Idempotent-Replay: true) instead of repeating the side effect. See Idempotency.
Path Parameters
Body
Response
The action was carried out, or, with dryRun: true, the preview of it.
- Option 1
- Option 2
The pitch after the action, or, with dryRun: true, the preview of it.