API Reference
The Sophic API provides programmatic access to your workspace's knowledge base. All endpoints return JSON and accept a Bearer credential — either a workspace API key or a Personal Access Token (PAT).
Base URL: https://app.sophic.so/api/v1
Authentication
All requests carry the credential in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \
https://app.sophic.so/api/v1/documents
- A workspace API key is bound to one workspace — no extra header needed.
- A PAT is user-scoped, so it must say which workspace to act in via the
x-sophic-workspace: <slug>header.
The read endpoints below accept either credential. The write endpoint (POST /api/ingest/cli, used by the MCP capture tool) requires a PAT — see Authentication.
The v1 read endpoints only serve workspace-visible content. Documents that live in team- or role-scoped folders are not returned.
Endpoints
Documents
| Method | Path | Description |
|---|---|---|
GET | /api/v1/documents | List documents (paginated) |
GET | /api/v1/documents/:id | Get a single document with full content |
Search
| Method | Path | Description |
|---|---|---|
GET | /api/v1/search?q=... | Semantic (vector) search over document sections |
GET | /api/v1/grep?q=... | Exact-string / regex search across documents |
Captures
| Method | Path | Description |
|---|---|---|
GET | /api/v1/captures | List raw buffer captures before consolidation |
POST | /api/ingest/cli | Submit a capture (PAT only — used by the MCP capture tool) |
Common patterns
Pagination
The list endpoints (/documents, /captures) support limit and offset:
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.sophic.so/api/v1/documents?limit=20&offset=40"
| Parameter | Default | Max | Description |
|---|---|---|---|
limit | 50 | 100 | Results per page |
offset | 0 | — | Number of results to skip |
/documents and /captures also accept ?source=A,B to filter by one or more source values.
grep
When you have an exact identifier rather than a concept — an env-var name, a function name, an error string — use grep instead of search. It runs literal (or regex) line-level matching across the workspace's documents.
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.sophic.so/api/v1/grep?q=SOPHIC_API_KEY"
| Parameter | Type | Default | Max | Description |
|---|---|---|---|---|
q | string | — | 500 chars | The string (or regex) to find. Required. |
regex | boolean | false | — | Treat q as a POSIX regex |
limit | number | 50 | 200 | Maximum matching lines |
max_per_doc | number | 5 | 50 | Cap on matches per document |
Returns { text, results } — text is a ripgrep-shaped block (<title> (<id>):<line>: <text>) and results is the structured rows.
Error responses
All errors return a JSON object with an error field:
{
"error": "Search failed"
}
| Status | Meaning |
|---|---|
| 400 | Invalid or missing parameters |
| 401 | Missing or invalid credential |
| 403 | Credential type not allowed for this endpoint |
| 404 | Document not found or not accessible |
| 500 | Server error |
Next steps
- Authentication — API key and PAT management
- Documents — List and retrieve documents
- Search — Semantic search endpoint