Open Dashboard
API REFERENCE / V1

Build on your search.

A JSON API for your account’s explicitly granted data and actions.

Authentication

Create an API key in Developer settings. Every request requires a bearer token. Browser sign-in cookies do not authorize this API.

Base URL
https://www.ultrasearch.cc/api/v1
First request · shell
curl https://www.ultrasearch.cc/api/v1/search   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"query":"quarterly plan","limit":20}'

Replace YOUR_API_KEY with your stored secret. Grant search and choose the folders and connectors to search. Local operations need the desktop app online and signed in.

Endpoints

Paths below are relative to /api/v1. Each operation checks its required scope and resource grants.

POST/search

Search granted local folders and connected apps.

Required scope: search

{"query":"quarterly plan","limit":20}

GET/connections

List permitted connections and discover tool IDs and their input schemas.

Required scope: connections:read

No body

POST/files/read

Read a file inside a granted folder; up to 1,000,000 bytes.

Required scope: files:read

{"path":"C:\\Projects\\notes.txt","maxBytes":100000}

POST/files/list

List a granted directory; limit up to 1,000.

Required scope: files:list

{"path":"C:\\Projects","limit":100}

GET/clipboard

Read desktop clipboard text.

Required scope: clipboard:read

No body

PUT/clipboard

Replace desktop clipboard text; up to 100,000 characters.

Required scope: clipboard:write

{"text":"Hello from my integration"}

POST/open

Open an allowed document or media file on your desktop. Folders, executables, scripts, and URLs are not supported.

Required scope: resources:open

{"path":"C:\\Projects\\notes.txt"}

GET/tools

Discover operation names permitted by this key. Use /connections for connector tool IDs.

Required scope: Any valid API key

No body

POST/tools

Read from connected apps or prepare and confirm a supported write.

Required scope: connections:read or connections:write

See connected-app example below

Connected-app tools

Discover permitted connector tools with GET /connections. Use the returned tool ID and input schema. A read action uses the following request:

POST /api/v1/tools
{
  "operation": "connection_read",
  "arguments": {
    "toolId": "github.search",
    "arguments": {
      "query": "release"
    }
  }
}

For a write, send operation: "connection_prepare_write" with arguments: { toolId, arguments: { ... } }. Show the returned proposal to the user. Only after they approve that exact action, send its token back:

POST /api/v1/tools · confirm approved proposal
{
  "operation": "connection_confirm_write",
  "arguments": {
    "token": "PREPARED_PROPOSAL_TOKEN",
    "accept": true
  }
}

Set accept: false to reject. Proposals are bound to the credential that prepared them and expire. The key needs connections:write, an allowed connector, and the connector’s own write authorization.

Errors and limits

  • 400 — invalid JSON, arguments, or an unsupported operation.
  • 401 — missing, invalid, expired, revoked, or wrong-type key.
  • 403 — scope or resource is not granted.
  • 409 — action conflicts with current state.
  • 413 — request or content exceeds a size limit.
  • 429 — too many requests; wait before retrying.
  • 502 / 503 / 504 — provider or desktop unavailable, or operation timed out.

Keep queries and reads bounded. Retry reads with backoff when a dependency is unavailable. Review write state before retrying a confirmation to avoid duplicate actions.