List opportunities

curl --request GET \
  --url https://app.searchable.com/api/mcp/projects/{projectId}/opportunities \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.searchable.com/api/mcp/projects/{projectId}/opportunities"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.searchable.com/api/mcp/projects/{projectId}/opportunities', 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/projects/{projectId}/opportunities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.searchable.com/api/mcp/projects/{projectId}/opportunities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.searchable.com/api/mcp/projects/{projectId}/opportunities")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "project": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "domain": "<string>"
  },
  "summary": {
    "total": 123,
    "bySource": {},
    "byImpact": {
      "critical": 123,
      "high": 123,
      "medium": 123,
      "low": 123
    }
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "returnedCount": 123,
    "hasMore": true,
    "totalCount": 123,
    "nextOffset": 123
  },
  "opportunities": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "title": "<string>",
      "description": "<string>",
      "source": "<string>",
      "category": "<string>",
      "scope": "<string>",
      "actionType": "<string>",
      "completedAt": "2023-11-07T05:31:56Z",
      "dismissedAt": "2023-11-07T05:31:56Z",
      "dismissedReason": "<string>",
      "autoResolvedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

Opportunities

List opportunities

Actionable opportunities Searchable surfaced for the project — prioritized fix/write/audit suggestions derived from visibility, sentiment, sources, traffic, prompts, site health, and articles. Read-only. Defaults to active opportunities (pass status or includeResolved=true to widen, source/impact to narrow); returns them in the product’s priority order plus global stats. Regular-project feature — pitch projects are rejected (403 pitch_not_supported).

GET

api

mcp

projects

{projectId}

opportunities

List opportunities

curl --request GET \
  --url https://app.searchable.com/api/mcp/projects/{projectId}/opportunities \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.searchable.com/api/mcp/projects/{projectId}/opportunities"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.searchable.com/api/mcp/projects/{projectId}/opportunities', 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/projects/{projectId}/opportunities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.searchable.com/api/mcp/projects/{projectId}/opportunities"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.searchable.com/api/mcp/projects/{projectId}/opportunities")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "project": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "domain": "<string>"
  },
  "summary": {
    "total": 123,
    "bySource": {},
    "byImpact": {
      "critical": 123,
      "high": 123,
      "medium": 123,
      "low": 123
    }
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "returnedCount": 123,
    "hasMore": true,
    "totalCount": 123,
    "nextOffset": 123
  },
  "opportunities": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "title": "<string>",
      "description": "<string>",
      "source": "<string>",
      "category": "<string>",
      "scope": "<string>",
      "actionType": "<string>",
      "completedAt": "2023-11-07T05:31:56Z",
      "dismissedAt": "2023-11-07T05:31:56Z",
      "dismissedReason": "<string>",
      "autoResolvedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ]
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "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": {}
  }
}

Authorizations

Authorization

string

header

required

A Searchable API key, created under Settings → Workspace → Integrations. 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.

Path Parameters

projectId

string<uuid>

required

The project id.

Query Parameters

status

enum<string>

Filter by status. Defaults to active unless includeResolved=true.

Available options:

active,

completed,

dismissed,

auto_resolved

includeResolved

enum<string>

Pass true to widen beyond active opportunities.

Available options:

true,

false

source

string

Filter opportunities by their originating source.

impact

enum<string>

Filter opportunities by impact level.

Available options:

critical,

high,

medium,

low

limit

integer

Page size. Defaults and caps vary by endpoint (see each operation's description); big list endpoints (cited domains/URLs, prompts, opportunities) cap at 1000, issues at 5000. Values above an endpoint's cap are clamped server-side, never rejected.

Required range: x >= 1

offset

integer

default:0

Row offset for pagination.

Required range: x >= 0

format

enum<string>

default:json

Response format. csv returns the operation's main row set as a downloadable UTF-8 CSV (RFC 4180, BOM-prefixed, spreadsheet-formula-hardened) instead of the JSON envelope. Pagination params apply unchanged — export beyond one page by walking offsets.

Available options:

json,

csv

Response

Opportunities.

project

object

required

Show child attributes

summary

object

required

Show child attributes

pagination

object

required

Standard offset-pagination block.

Show child attributes

opportunities

object[]

required

Show child attributes

Get Started

Endpoints

List opportunities

Authorizations

Path Parameters

Query Parameters

Response