Search

Workspace search is semantic, not substring: you ask in natural language and get back the passages that mean the same thing. Indexing covers more than text - images, audio, video, and PDFs are indexed by content too, so “the slide with the revenue waterfall” is a workable query. For exact strings and regular expressions, use grep instead. It is faster, needs no index, and never guesses.

export ARG_API_KEY="arg_live_your_key_here"
export ARG_API="https://api.arg.ai"

Search a workspace

curl -sS -X POST "$ARG_API/api/workspaces/$WS/search" \
  -H "X-API-Key: $ARG_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "how we handle refunds for annual plans", "limit": 10}'

{
  "indexState": "ready",
  "results": [
    {
      "path": "/policies/billing.mdx",
      "name": "billing.mdx",
      "fileId": "argfile_…",
      "score": 0.82,
      "snippets": ["Annual plans are refunded pro rata within 30 days…"]
    }
  ]
}

Field	Description
`query`	Natural language, 2 to 2,000 characters. Required.
`limit`	Maximum results.
`pathPrefix`	Restrict the search to one folder.

Check `indexState` before trusting an empty result

Value	Meaning
`ready`	The workspace is indexed. No results means no matches.
`unindexed`	Nothing has been indexed yet. Results will be empty regardless of the query.
`disabled`	Search is off for this workspace.

An empty results array with indexState: "unindexed" is not “nothing matched” - it is “ask again later”. Handle the two differently in any code that acts on the outcome.

Search an organization

One call fans out across every workspace in the organization you can access:

curl -sS -X POST "$ARG_API/api/organizations/$ORG/search" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query": "vendor security questionnaire", "limit": 20}'

Pass workspaceIds to narrow it to a few workspaces instead of all of them.

Results respect file permissions

Search never leaks the existence of a file the caller cannot read. For members with access to specific files rather than the whole workspace, hits are filtered before the response is built, so counts cannot be used to infer what is hidden.

Managing the index

# What the workspace indexes today
curl -sS "$ARG_API/api/workspaces/$WS/search/settings" -H "X-API-Key: $ARG_API_KEY"

# Which file types are indexable
curl -sS "$ARG_API/api/workspaces/$WS/search/supported-types" -H "X-API-Key: $ARG_API_KEY"

# Rebuild the index in the background
curl -sS -X POST "$ARG_API/api/workspaces/$WS/search/reindex" -H "X-API-Key: $ARG_API_KEY"

Files are indexed as they change, so a reindex is for recovery and for after a bulk import, not for routine use.

Agents search too

semantic_search is a built-in agent tool, so an agent working in the workspace can find a file it was never told about. That is the main reason to keep an index healthy on a workspace agents work in: it is the difference between an agent that can answer from your documents and one that can only read what you named.

Tools - exact-match search with grep
Files - reading what search points at
Search API reference - every parameter

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Search a workspace

Check `indexState` before trusting an empty result

Search an organization

Results respect file permissions

Managing the index

Agents search too

​Search a workspace

​Check indexState before trusting an empty result

​Search an organization

​Results respect file permissions

​Managing the index

​Agents search too

​Related

Search a workspace

Check `indexState` before trusting an empty result

Search an organization

Results respect file permissions

Managing the index

Agents search too

Related