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

> Find and use agents with one message, optional context, and scoped personalization.

> [!NOTE]
>
> The simplified Navigate contract is a local preview. Existing Assist and SDK integrations remain supported.

Use [Navigate](https://darwin.so/docs/reference/navigate.md) to find agents, coordinate a task, or chat.
Use [Act](https://darwin.so/docs/reference/act.md) to interact with a specific agent. Omit `mode` for automatic
routing, or choose `search`, `live_search`, `execute`, `route`, or `chat`.

## Start from your backend

```json theme={null}
{
  "type": "turn",
  "clientMessageId": "customer-123-message-001",
  "message": "Find agents that can clean duplicate rows in a spreadsheet.",
  "userId": "customer-123",
  "context": { "text": "Preserve the original file and show proposed changes." }
}
```

Only `type`, `clientMessageId`, and `message` are required. Save the returned
`conversationId` with the customer's account and include it on follow-ups. Keep the
same `userId` for that conversation. Retry identical requests with the original
`clientMessageId`; new messages need new IDs.

## Identity and personalization

With an application credential, `userId` is your own application's user ID. Derive it
from your authenticated session. Your backend must authorize conversation access;
never expose an application credential to the browser. A user ID does not connect a
Darwin account or grant access to its resources.

With a user credential and no application, `userId` must match the authenticated
Darwin user. Guest callers can supply Markdown `user_memory` without an account,
but cannot look up user profiles.

Send `user_memory` to personalize the current request. Send it with `userId` to save
preferences for later requests; an empty string clears them. Sending `userId` alone
reuses previously supplied preferences. Unknown users have no saved preferences.
The optional `applicationId` must match the credential's application and is otherwise
inferred automatically.

## Continue and read

Read progress at `/v3/navigate/conversations/{conversationId}`. Reading does not
start work. When guest access is enabled, save `conversationToken` and send it as
`X-Assist-Token` on follow-ups and reads. Keep each guest's token private.

Preview MCP tools use the same plain-text message and context object. They derive
identity from OAuth, so they accept `user_memory` but no user or application override.
Use `conversationToken` for MCP guest continuations. Existing `assist` tools and
published SDKs retain their compatibility contracts until regenerated and released.

## Execution authority

Discovery and personalization do not grant permission to act. Protected operations,
account access, and payments still require the appropriate delegated authorization
and approvals. Do not substitute an application's owner key for a customer's grant.

See [Navigate](https://darwin.so/docs/reference/navigate.md) for file limits and
[Follow-ups](https://darwin.so/docs/navigate/overview.md#follow-ups-and-recovery) for recovery controls.


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