Public REST API (v1)

# Public REST API (v1) Sophic's public REST API lets you search, read, and capture knowledge programmatically. API access is a **Business-plan** feature, available on Business and Enterprise workspaces. ## Base URL & Authentication All endpoints live under: ``` https://app.sophic.so ``` Authenticate every request with a bearer token: ``` Authorization: Bearer ``` The token is either a **workspace API key** (prefixed `sophic_sk_`) or a **Personal Access Token (PAT)**. Credentials are stored only as SHA-256 hashes, never in plaintext, and can be revoked or set to expire. ## Creating an API Key 1. Open your workspace settings (workspace owners and admins only). 2. Create a new API key. 3. Assign **action scopes** — `read`, `capture`, and/or `admin`. 4. Choose a **folder-visibility role** (`admin`, `editor`, `viewer`, or `agent-only`) and an optional expiry. Read endpoints only return documents that live in **workspace-visible folders**. Role-restricted folders are filtered out. ## Endpoints ### Search (semantic) Best for concepts and fuzzy questions. Returns LLM-ready `text` plus structured `results`. ```bash curl "https://app.sophic.so/api/v1/search?q=deploy+rollback&limit=8" \ -H "Authorization: Bearer sophic_sk_..." ``` Response: ```json { "text": "...", "results": [ ] } ``` ### Grep (literal / regex) Best for exact identifiers like env-var names, function names, or error strings. ```bash curl "https://app.sophic.so/api/v1/grep?q=DATABASE_URL®ex=false&limit=50" \ -H "Authorization: Bearer sophic_sk_..." ``` Response: ```json { "text": "...", "results": [ ] } ``` ### List documents Supports `limit`, `offset`, and a comma-separated `source` filter. ```bash curl "https://app.sophic.so/api/v1/documents?limit=50&offset=0&source=slack,github" \ -H "Authorization: Bearer sophic_sk_..." ``` ### Get a document by ID ```bash curl "https://app.sophic.so/api/v1/documents/{id}" \ -H "Authorization: Bearer sophic_sk_..." ``` Returns the full document. ### Captures stream ```bash curl "https://app.sophic.so/api/v1/captures" \ -H "Authorization: Bearer sophic_sk_..." ``` ### Ingest a note (CLI ingest) Write a capture into the knowledge base. This endpoint requires a **PAT with the `capture` scope** plus the `x-sophic-workspace` header. Workspace API keys **cannot** write here. ```bash curl -X POST "https://app.sophic.so/api/ingest/cli" \ -H "Authorization: Bearer " \ -H "x-sophic-workspace: your-workspace-slug" \ -H "Content-Type: application/json" \ -d '{ "text": "Restart the worker after rotating the API key." }' ``` ## FAQ **Why does my API key get rejected on `/api/ingest/cli`?** Write access requires a Personal Access Token with the `capture` scope and the `x-sophic-workspace` header. Workspace API keys cannot write to this endpoint. **Why are some documents missing from search and list results?** Read endpoints only return documents in workspace-visible folders. Documents in role-restricted folders are excluded. **Where do I get an API key?** Workspace owners and admins create them in workspace settings. PATs are also issued when you run `sophic login` in the CLI. **Is the API available on my plan?** API access requires the Business plan or higher. Free and Basic workspaces don't include it.