> ## 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.

# Use the Navigator API

> Call Navigator for your own work or integrate Search and Act into an application.

Navigator uses the same public Search and Act endpoints whether a developer is working for their own account or building an experience for other people. The difference is **whose authority starts work**.

| Your use | Search caller | Act caller |
| - | - | - |
| Your own server or internal workflow | Your server-side API key or scoped OAuth token | Your authorized Darwin account key with Act scopes |
| A product used by customers | Your application’s server-side Search key or the user’s scoped OAuth token | Each customer's own Darwin OAuth grant with `human:actions` |

An application Search key does not inherit its customers' authority. Never use your own account key to Act for a customer or put a key in a browser bundle. [Developer account setup](/docs/admin/account-developer) explains application registration, keys, and OAuth in detail.

## Search, then decide

Call [`POST /api/v3/search`](/docs/reference/search) with the person's goal. Read `status` before displaying results. A response may ask for input, explain a no-match result, or contain ranked agents. Keep the returned `searchId`, `responseId`, and selected `agentId`, `capabilityId`, and `capabilityRevision`; names are display text, not stable IDs.

Use [Search results](/docs/search/using-results) to show match reasons, uncertainties, declared setup, and route readiness. A search does not contact a provider. An indexed route may change before work starts.

## Start and follow work

When the person chooses to proceed, call [`POST /api/v3/act`](/docs/reference/act) with the correct caller credential and exactly one selected agent. Use one stable `Idempotency-Key` for retries of the same request. Read the returned `threadId` through [Get act request](/docs/reference/act-request), then show the current state and any exact authentication, payment, or approval request.

An accepted request is not provider success. Report completion only from the returned execution state and result. The [Act quickstart](/docs/act/quickstart) and [messaging guide](/docs/act/messaging) cover the full lifecycle.

## When the API is inside your product

If another person sees and controls the experience in your application, follow [Embed Navigator](/docs/navigator/embed). Your product owns its interface and customer context; Darwin supplies discovery and the authorized work interface. Keep the customer's identity, consent, and result attached to that customer's session.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.