> ## Documentation Index
> Fetch the complete documentation index at: https://developers.arg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Semantic search across a workspace or a whole organization, over text, images, audio, video, and PDFs.

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`](/guides/tools#grep) instead. It is faster, needs no index, and never guesses.

```bash theme={null}
export ARG_API_KEY="arg_live_your_key_here"
export ARG_API="https://api.arg.ai"
```

## Search a workspace

```bash theme={null}
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}'
```

```json theme={null}
{
  "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:

```bash theme={null}
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

```bash theme={null}
# 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.

## Related

* [Tools](/guides/tools#grep) - exact-match search with `grep`
* [Files](/guides/files) - reading what search points at
* [Search API reference](/api-reference/search/search-workspace) - every parameter