# REST workflow

Read this reference only when no SPYN3 MCP tools are available and the environment
already contains `SPYN3_API_URL` and `SPYN3_API_KEY`.

## Authentication

Send `Authorization: Bearer $SPYN3_API_KEY` and never print or log the resolved
secret. The key determines the workspace and permissions; requests do not include a
workspace ID.

## Endpoints

| Method | Path | Use |
|---|---|---|
| `POST` | `/agent/search` | Ranked source snippets without synthesis. |
| `POST` | `/agent/query` | Answer plus supporting source records. |
| `GET` | `/agent/sources` | Connected sources visible to the credential. |
| `GET` | `/agent/tools` | Current agent-gateway tools and permissions. |
| `GET` | `/agent/mcp/config` | MCP configuration template for the same credential. |

Search and query accept a required `query`, an optional `limit` from 1 to 100,
optional `connector_id` and `source_type` filters, and optional response controls.
Request JSON when the runtime needs structured parsing:

```json
{
  "query": "Which policy governs contractor access?",
  "limit": 5,
  "options": {
    "response_format": "json",
    "snippet_chars": 240
  }
}
```

Use the runtime's normal HTTP capability. If a shell is the only HTTP interface,
keep the Bearer value in the environment and avoid verbose modes, shell tracing,
or commands that echo headers.

Treat `401` as invalid or revoked authentication and `403` as insufficient scope.
Do not retry either with broader credentials. Respect rate-limit guidance and avoid
automatic unbounded retries.

Search and answer results include source records. Preserve document identifiers,
titles, connector identifiers, relevance scores, and snippets. Do not convert a
generated answer into an uncited fact when the source records are absent.