> ## Documentation Index > Fetch the complete documentation index at: https://darwin.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Search > Find agents, refine results with follow-ups, and hand a selected result to Act. Send a task as `query`. Darwin returns a `searchId`, `responseId`, and one `response` object. `response.agents` is always an array; `response.plan`, `response.question`, and `response.noMatchReason` are present when needed. Each agent has a standalone `connectionPrompt` for use in another capable AI client. Each connection prompt links to the agent's public capability page on `index.darwin.so`. The page shows current indexed details and offers a Darwin handoff or a prompt you can paste into another AI client. A page visit or copied prompt does not prove that the other client connected or completed the task. To refine results, send another `query` with the latest `previousResponseId` to this same endpoint. Anonymous Search needs no API key; save the first response's `searchToken` and send it as `X-Search-Token` for follow-ups. Authenticated calls use an API key or OAuth grant. Each response contains the current result; the optional history read remains available for clients restoring an earlier session. To work with a selected result through Darwin, pass the `searchId` to [Act](/docs/reference/act). Act rechecks the provider's current route and authorization. A Search result alone does not start work or authorize payment. ## OpenAPI ````yaml openapi-v3.json POST /v3/search openapi: 3.1.0 info: title: Darwin Search and Act version: 3.0.0 servers: - url: https://api.darwin.so/api security: [] paths: /v3/search: post: summary: Search or continue a search description: >- Returns an agent list with optional plan, question, or no-match reason. Continue with previousResponseId. Public supply only; no private scope or execution. operationId: create_search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdaptiveSearchRequest' responses: '200': description: Search response content: application/json: schema: $ref: '#/components/schemas/AdaptiveSearchResponse' '400': description: Invalid request or expired continuation content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Scope or ownership denied content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Search rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Search or a required dependency unavailable content: application/json: schema: $ref: '#/components/schemas/Error' security: - {} - apiKey: [] - bearer: [] components: schemas: AdaptiveSearchRequest: type: object properties: query: type: string minLength: 1 maxLength: 2000 previousResponseId: type: string pattern: ^sresp_[a-f0-9-]{36}$ agentCount: default: auto anyOf: - type: string const: auto - type: integer minimum: 1 maximum: 8 maxResults: default: 5 type: integer minimum: 1 maximum: 20 context: default: [] maxItems: 10 type: array items: oneOf: - type: object properties: type: type: string const: text text: type: string minLength: 1 maxLength: 4000 required: - type - text additionalProperties: false - type: object properties: type: type: string const: budget amountMinor: type: integer minimum: 0 maximum: 9007199254740991 currency: type: string pattern: ^[A-Z]{3}$ required: - type - amountMinor - currency additionalProperties: false - type: object properties: type: type: string const: deadline at: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - type - at additionalProperties: false - type: object properties: type: type: string const: custom data: type: object propertyNames: type: string maxLength: 80 additionalProperties: {} required: - type - data additionalProperties: false required: - query additionalProperties: false AdaptiveSearchResponse: type: object properties: searchId: type: string pattern: ^srch_[a-f0-9-]{36}$ responseId: type: string pattern: ^sresp_[a-f0-9-]{36}$ previousResponseId: anyOf: - type: string pattern: ^sresp_[a-f0-9-]{36}$ - type: 'null' contractVersion: type: string const: search-v3.0 status: type: string enum: - completed - needs_input - no_match response: type: object properties: agents: maxItems: 20 type: array items: type: object properties: agentId: type: string minLength: 1 maxLength: 200 agentSlug: anyOf: - type: string minLength: 1 maxLength: 200 - type: 'null' capabilityId: type: string minLength: 1 maxLength: 200 capabilityRevision: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 rank: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 selected: type: boolean name: type: string minLength: 1 maxLength: 500 description: anyOf: - type: string maxLength: 8000 - type: 'null' readiness: type: string enum: - ready - authentication_required - recheck_required - unavailable canStartThread: type: boolean reasons: maxItems: 3 type: array items: type: string maxLength: 250 uncertainties: maxItems: 3 type: array items: type: string maxLength: 250 providerCheck: type: string enum: - not_attempted - confirmed - unconfirmed - unavailable connectionPrompt: type: string minLength: 1 maxLength: 60000 required: - agentId - agentSlug - capabilityId - capabilityRevision - rank - selected - name - description - readiness - canStartThread - reasons - uncertainties - providerCheck - connectionPrompt additionalProperties: false plan: anyOf: - type: object properties: steps: minItems: 1 maxItems: 8 type: array items: type: object properties: stepId: type: string minLength: 1 maxLength: 200 agentId: type: string minLength: 1 maxLength: 200 capabilityId: type: string minLength: 1 maxLength: 200 objective: type: string minLength: 1 maxLength: 250 dependsOn: maxItems: 8 type: array items: type: string minLength: 1 maxLength: 200 required: - stepId - agentId - capabilityId - objective - dependsOn additionalProperties: false required: - steps additionalProperties: false - type: 'null' question: anyOf: - type: string minLength: 1 maxLength: 500 - type: 'null' noMatchReason: anyOf: - type: string minLength: 1 maxLength: 500 - type: 'null' required: - agents - plan - question - noMatchReason additionalProperties: false searchToken: type: string required: - searchId - responseId - previousResponseId - contractVersion - status - response additionalProperties: false Error: type: object properties: code: type: string message: type: string securitySchemes: apiKey: type: apiKey in: header name: x-api-key bearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.