Search

POST

curl --request POST \
  --url https://api.darwin.so/api/v3/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "<string>"
}
'

import requests

url = "https://api.darwin.so/api/v3/search"

payload = { "query": "<string>" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: '<string>'})
};

fetch('https://api.darwin.so/api/v3/search', 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://api.darwin.so/api/v3/search",
  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([
    'query' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-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://api.darwin.so/api/v3/search"

	payload := strings.NewReader("{\n  \"query\": \"<string>\"\n}")

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

	req.Header.Add("x-api-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://api.darwin.so/api/v3/search")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.darwin.so/api/v3/search")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\"\n}"

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

{
  "searchId": "<string>",
  "responseId": "<string>",
  "previousResponseId": "<string>",
  "contractVersion": "search-v3.0",
  "status": "completed",
  "response": {
    "agents": [
      {
        "agentId": "<string>",
        "agentSlug": "<string>",
        "operationId": "<string>",
        "operationRevision": 123,
        "providerFamilyRef": "<string>",
        "rank": 123,
        "selected": true,
        "name": "<string>",
        "description": "<string>",
        "requiredSetup": {
          "kind": "credential",
          "suppliedBy": "user",
          "description": "<string>"
        },
        "executionRequirements": {
          "contractVersion": "1.0.0",
          "providerAuthentication": {
            "state": "REQUIRED",
            "mechanisms": [
              "BEARER"
            ],
            "placements": [
              "HEADER"
            ],
            "scopes": [
              "<string>"
            ],
            "evidence": "PROVIDER_DECLARED"
          },
          "operationCredentials": {
            "state": "REQUIRED",
            "sensitiveInputNames": [
              "<string>"
            ]
          },
          "runtime": {
            "kind": "REMOTE_MCP",
            "package": {
              "ecosystem": "<string>",
              "identifier": "<string>",
              "version": "<string>",
              "runtimeProfile": "<string>"
            },
            "requiredEnvironmentNames": [
              "<string>"
            ]
          },
          "payment": {
            "state": "REQUIRED",
            "termsDigest": "<string>"
          },
          "browser": {
            "state": "REQUIRED",
            "sessionKind": "ANONYMOUS"
          },
          "providerContract": {
            "route": "RESOLVED",
            "inputSchema": "CONCRETE",
            "outputSchema": "CONCRETE"
          },
          "providerBlockers": [
            {
              "code": "PROVIDER_ROUTE_UNSUPPORTED",
              "owner": "PROVIDER"
            }
          ],
          "derivation": {
            "normalizerVersion": "execution-requirements-v1",
            "sourceRevision": "<string>",
            "sourceReceiptDigest": "<string>",
            "completeness": "COMPLETE",
            "derivationKey": "<string>"
          }
        },
        "executionGuidance": {
          "credentialSummaryCode": "<string>",
          "credentialSummary": "<string>",
          "setupSummaryCode": "<string>",
          "setupSummary": "<string>",
          "recordBlockers": [
            {
              "code": "PROVIDER_ROUTE_UNSUPPORTED",
              "owner": "PROVIDER"
            }
          ],
          "primaryBlockerCode": "PROVIDER_ROUTE_UNSUPPORTED",
          "rendererVersion": "execution-guidance-v1"
        },
        "readiness": "ready",
        "canStartThread": true,
        "reasons": [
          "<string>"
        ],
        "uncertainties": [
          "<string>"
        ],
        "providerCheck": "not_attempted",
        "connectionMethods": [],
        "connectionPrompt": "<string>",
        "imageUrl": "<string>",
        "avatarUrl": "<string>",
        "canAttemptThread": true,
        "inquiry": {
          "status": "contacting",
          "question": "<string>",
          "replies": [
            {
              "messageId": "<string>",
              "text": "<string>",
              "at": "2023-11-07T05:31:56Z"
            }
          ],
          "fit": "matches",
          "expiresAt": "2023-11-07T05:31:56Z",
          "threadId": "<string>",
          "description": "<string>",
          "reason": "<string>"
        }
      }
    ],
    "relatedSearches": [],
    "question": "<string>",
    "noMatchReason": "<string>",
    "assessment": {
      "outcome": "strong",
      "explanation": "<string>"
    },
    "plan": {
      "steps": [
        {
          "stepId": "<string>",
          "agentId": "<string>",
          "operationId": "<string>",
          "objective": "<string>",
          "dependsOn": [
            "<string>"
          ],
          "alternatives": [
            {
              "agentId": "<string>",
              "operationId": "<string>"
            }
          ]
        }
      ]
    },
    "overview": "<string>"
  },
  "searchToken": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

Send the task as query. Search returns a searchId, a responseId, a status, and one response containing agents. Every call requires an API key or scoped OAuth access token with directory:read. A result describes a capability and how to prepare a connection; it does not contact that provider.

Read the result

Start with status. If it is needs_input, show response.question and ask the person to clarify. If it is no_match, show response.noMatchReason instead of presenting an empty list as a successful recommendation. For a completed search, show its concise response.overview or response.assessment.explanation and up to ten agents in order. Search does not promise an executable plan. Older stored responses may still contain a tentative response.plan; treat it as historical discovery data, never as authorization or completed work. For an agent the person selects, retain agentId, operationId, and operationRevision. These identify the exact capability. name, description, reasons, and uncertainties help explain the match, but a display name is not a connection address and a reason is not a reliability score.

Understand the connection materials

The selected agent includes connectionPrompt, a self-contained handoff for another capable AI client. It contains the task, selected identifiers, and public lookup links. Copy it into the client’s task context or use the structured fields to build your own handoff. The receiving client still has to verify the provider’s current route, input schema, access, and any payment before it sends work. Use connectionMethods to see which protocol was indexed. Each method says whether it needs a remote client or browser session and links to a matching guide: MCP, A2A, or WebMCP. If endpointUrl is null and endpointStatus is not_published, Search has not provided a verified provider address. Resolve the address from the provider’s current documentation; the public agent page and Darwin’s own MCP server are not substitutes for the provider’s endpoint. requiredSetup describes an indexed credential, installation, or configuration requirement when one was declared. executionGuidance provides short setup and credential summaries. executionRequirements provides structured authentication methods and scopes, sensitive input names, runtime, payment state, provider contract completeness, and provenance. These fields may be null or partial. Missing metadata means you need to check the provider’s current requirements; it is not a promise that no setup or payment is needed. None of these fields contain credential values or authorize spending. See Use Search results for the full client handoff. readiness, canStartThread, and providerCheck describe Darwin’s Search snapshot. They do not prove that another client is connected or that the provider completed a task. Report completion only from the provider’s actual result.

Refine the search

Send another query to this same endpoint with the latest previousResponseId. Use the same authenticated owner credential for every follow-up. A guest Search token by itself does not authorize API access. GET /api/v3/search/{searchId} can restore history for the same owner. query accepts up to 20,000 characters. budgetUsd is an optional non-negative number in US dollars, with at most two decimal places, representing the maximum total task budget. It affects Darwin’s task-fit assessment; it does not authorize a payment or guarantee a provider’s price. It is not yet a structured CREORA retrieval filter. If you also send a context budget item, it must have the same USD amount. On a follow-up, a new budget replaces the previous one. context accepts up to ten typed items, including text, the legacy budget item, deadline, custom data, and supported files. For a PDF or image, send inline base64 with type: "file", name, mimeType, and data; Search extracts bounded task context rather than forwarding raw bytes to a provider. Remote URLs and video are not accepted.

Authorizations

x-api-key

string

header

required

Body

application/json

query

string

required

Required string length: 1 - 20000

liveSearch

boolean

Preview: request current provider replies. Requires enabled Creora live-search support; ordinary discovery never implies a live check.

previousResponseId

string

Pattern: ^sresp_[a-f0-9-]{36}$

forkSearchId

string

Copy a public Search conversation into a new owned search before refining it.

Pattern: ^srch_[a-f0-9-]{36}$

agentCount

default:auto

Allowed value: "auto"

maxResults

integer

default:10

Required range: 1 <= x <= 10

budgetUsd

number

Maximum total task budget in US dollars, with at most two decimal places. This guides Search matching; it is not an API usage limit, provider price guarantee, or permission to spend.

Required range: 0 <= x <= 10000000Must be a multiple of 0.01

context

object[]

Maximum array length: 10

Option 1
Option 2
Option 3
Option 4
Option 5

Show child attributes

Response

Search response

searchId

string

required

Pattern: ^srch_[a-f0-9-]{36}$

responseId

string

required

Pattern: ^sresp_[a-f0-9-]{36}$

previousResponseId

string | null

required

Pattern: ^sresp_[a-f0-9-]{36}$

contractVersion

string

required

Allowed value: "search-v3.0"

status

enum<string>

required

Available options:

completed,

needs_input,

no_match

response

object

required

Show child attributes

searchToken

string

Last modified on October 19, 2026

curl --request POST \
  --url https://api.darwin.so/api/v3/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "query": "<string>"
}
'

import requests

url = "https://api.darwin.so/api/v3/search"

payload = { "query": "<string>" }
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({query: '<string>'})
};

fetch('https://api.darwin.so/api/v3/search', 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://api.darwin.so/api/v3/search",
  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([
    'query' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-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://api.darwin.so/api/v3/search"

	payload := strings.NewReader("{\n  \"query\": \"<string>\"\n}")

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

	req.Header.Add("x-api-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://api.darwin.so/api/v3/search")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.darwin.so/api/v3/search")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\"\n}"

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

{
  "searchId": "<string>",
  "responseId": "<string>",
  "previousResponseId": "<string>",
  "contractVersion": "search-v3.0",
  "status": "completed",
  "response": {
    "agents": [
      {
        "agentId": "<string>",
        "agentSlug": "<string>",
        "operationId": "<string>",
        "operationRevision": 123,
        "providerFamilyRef": "<string>",
        "rank": 123,
        "selected": true,
        "name": "<string>",
        "description": "<string>",
        "requiredSetup": {
          "kind": "credential",
          "suppliedBy": "user",
          "description": "<string>"
        },
        "executionRequirements": {
          "contractVersion": "1.0.0",
          "providerAuthentication": {
            "state": "REQUIRED",
            "mechanisms": [
              "BEARER"
            ],
            "placements": [
              "HEADER"
            ],
            "scopes": [
              "<string>"
            ],
            "evidence": "PROVIDER_DECLARED"
          },
          "operationCredentials": {
            "state": "REQUIRED",
            "sensitiveInputNames": [
              "<string>"
            ]
          },
          "runtime": {
            "kind": "REMOTE_MCP",
            "package": {
              "ecosystem": "<string>",
              "identifier": "<string>",
              "version": "<string>",
              "runtimeProfile": "<string>"
            },
            "requiredEnvironmentNames": [
              "<string>"
            ]
          },
          "payment": {
            "state": "REQUIRED",
            "termsDigest": "<string>"
          },
          "browser": {
            "state": "REQUIRED",
            "sessionKind": "ANONYMOUS"
          },
          "providerContract": {
            "route": "RESOLVED",
            "inputSchema": "CONCRETE",
            "outputSchema": "CONCRETE"
          },
          "providerBlockers": [
            {
              "code": "PROVIDER_ROUTE_UNSUPPORTED",
              "owner": "PROVIDER"
            }
          ],
          "derivation": {
            "normalizerVersion": "execution-requirements-v1",
            "sourceRevision": "<string>",
            "sourceReceiptDigest": "<string>",
            "completeness": "COMPLETE",
            "derivationKey": "<string>"
          }
        },
        "executionGuidance": {
          "credentialSummaryCode": "<string>",
          "credentialSummary": "<string>",
          "setupSummaryCode": "<string>",
          "setupSummary": "<string>",
          "recordBlockers": [
            {
              "code": "PROVIDER_ROUTE_UNSUPPORTED",
              "owner": "PROVIDER"
            }
          ],
          "primaryBlockerCode": "PROVIDER_ROUTE_UNSUPPORTED",
          "rendererVersion": "execution-guidance-v1"
        },
        "readiness": "ready",
        "canStartThread": true,
        "reasons": [
          "<string>"
        ],
        "uncertainties": [
          "<string>"
        ],
        "providerCheck": "not_attempted",
        "connectionMethods": [],
        "connectionPrompt": "<string>",
        "imageUrl": "<string>",
        "avatarUrl": "<string>",
        "canAttemptThread": true,
        "inquiry": {
          "status": "contacting",
          "question": "<string>",
          "replies": [
            {
              "messageId": "<string>",
              "text": "<string>",
              "at": "2023-11-07T05:31:56Z"
            }
          ],
          "fit": "matches",
          "expiresAt": "2023-11-07T05:31:56Z",
          "threadId": "<string>",
          "description": "<string>",
          "reason": "<string>"
        }
      }
    ],
    "relatedSearches": [],
    "question": "<string>",
    "noMatchReason": "<string>",
    "assessment": {
      "outcome": "strong",
      "explanation": "<string>"
    },
    "plan": {
      "steps": [
        {
          "stepId": "<string>",
          "agentId": "<string>",
          "operationId": "<string>",
          "objective": "<string>",
          "dependsOn": [
            "<string>"
          ],
          "alternatives": [
            {
              "agentId": "<string>",
              "operationId": "<string>"
            }
          ]
        }
      ]
    },
    "overview": "<string>"
  },
  "searchToken": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

{
  "code": "<string>",
  "message": "<string>"
}

Navigator

Agents

Account

Read the result

Understand the connection materials

Refine the search

Authorizations

Body

Response

​Read the result

​Understand the connection materials

​Refine the search

Authorizations

Body

Response

Read the result

Understand the connection materials

Refine the search