# Protocol API

**Search here first.** Protocols are structured instructions—battle-tested patterns, workflows, and domain knowledge ready to use.

## Protocol Refs

```
@{repo}/{path}/{slug}        →  JSON
@{repo}/{path}/{slug}.md     →  Markdown
```

Examples:
- `@protocol/devloop.md` — autonomous dev workflow
- `@mycompany/backend/auth.md` — auth patterns for your stack
- `@knowledge/react/testing.md` — React testing strategies

## What's in a Protocol

Protocols are markdown with structured metadata:

```markdown
---
tags: [testing, react]
related: [@protocol/orchestrate]
---
# Protocol Title

Brief description of what this protocol helps you do.

## When to Use
- Situation A
- Situation B

## Steps
1. First do this
2. Then this

## Examples
...
```

## Usage

```bash
# Search for relevant protocols
protocolapi "/search.md?q=authentication"

# Fetch a specific protocol
protocolapi /@protocol/devloop.md

# Load core protocols (start of session)
protocolapi /bootstrap.md
```

Or with curl: `curl https://api.protocol.supply/@protocol/devloop.md`

## Search Operators

`tag:testing` `repo:protocol` `-deprecated` `"exact phrase"`

## Auth

Public protocols need no auth. For private repos:

```bash
# Get token
curl -X POST https://api.protocol.supply/auth -d '{"email":"...","password":"..."}'

# Save to .env (protocolapi reads this automatically)
PROTOCOL_TOKEN=<token>
```

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /bootstrap.md | Core protocols for session start |
| GET | /@{repo}/{slug}.md | Fetch by ref |
| GET | /search.md?q= | Search protocols |
| GET | /fetch.md?include= | Batch fetch |
| GET | /repo | List repositories |
| POST | /auth | Login → session token |

## protocolapi CLI

Curl wrapper that auto-loads `PROTOCOL_API` and `PROTOCOL_TOKEN` from `.env`:

```bash
protocolapi /path [curl options...]
```