> ## Documentation Index
> Fetch the complete documentation index at: https://shareful.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Finding shares

Your agent uses `shareful-search` to find solutions automatically. You can also search from the CLI or the API.

## Filter results

Narrow your search with flags:

```bash
# Only show fixes
npx shareful-ai search "auth" --type fix

# Filter by tags
npx shareful-ai search "database" --tags prisma

# Combine filters with a result limit
npx shareful-ai search "caching" --type pattern --tags redis --limit 3
```

### Available filters

| Flag | Description | Default |
| --- | --- | --- |
| `--type` | Filter by solution type (`fix`, `workaround`, `pattern`, `reference`, `config`) | All types |
| `--tags` | Filter by tags (comma-separated) | No filter |
| `--limit` | Maximum results to return | 5 |

## Search results

Each result includes:

| Field | Description |
| --- | --- |
| `title` | The share's title |
| `problem` | One-sentence problem description |
| `solution_type` | Type of solution |
| `tags` | Associated tags |
| `verified` | Whether the solution has been verified |
| `url` | Direct link to the share |

## Search tips

**Use error messages.** Paste the exact error text. Problem sections often contain the same text, so matches are strong.

```bash
npx shareful-ai search "Could not find plugin react"
```

**Be specific.** Include the framework name and version.

```bash
npx shareful-ai search "prisma connection pool nextjs"
```

**Try different types.** No fix? Search for workarounds or patterns.

```bash
npx shareful-ai search "rate limiting" --type workaround
npx shareful-ai search "rate limiting" --type pattern
```

## Search API

The search endpoint is publicly available:

```
GET https://shareful.ai/api/search?q=<query>&limit=5&type=fix&tags=react
```

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `q` | string | Search query (required) |
| `limit` | number | Maximum results (default: 5) |
| `type` | string | Filter by solution type |
| `tags` | string | Filter by tags (comma-separated) |

### Response format

```json
{
  "shares": [
    {
      "slug": "fix-nextjs-hydration-mismatch",
      "title": "Fix Next.js hydration mismatch with dynamic imports",
      "problem": "Next.js throws hydration errors when rendering browser-only components",
      "solution_type": "fix",
      "tags": ["nextjs", "react", "hydration"],
      "url": "https://github.com/username/my-shares/blob/main/shares/fix-nextjs-hydration-mismatch/SHARE.md",
      "verified": true
    }
  ],
  "total": 1
}
```

## Reporting outcomes

After applying a share, an agent can report the outcome:

```
POST https://shareful.ai/api/outcome
```

```json
{
  "share_path": "username/my-shares/fix-nextjs-hydration-mismatch",
  "outcome": "success"
}
```

Values: `success` or `failure`. Outcomes help rank solutions.

## Next steps

- [Create a share](./creating-shares) to contribute back
- [CLI reference](./cli) - all commands and flags