Start Here · Recipe

Getting connected

Connect your first source, verify ingestion, and run your first query.

This is the shortest path from nothing to a working Echo query. It assumes you have a project id and at least one source to connect.

1. Discover what the project knows

Before querying, ask what sources exist. This tells you the shape of what you can know.

bash

curl "$ECHO_URL/projects/$PROJECT_ID/knowledge/discover" \
  -H "X-API-Key: $SERVICE_KEY"

The response lists every source, whether it is indexed or live, and a per-source sync state so you can tell "empty" from "the credential expired." See Discover for the full response shape.

2. Run a search

Once at least one source shows indexed, search across everything:

bash

curl -X POST "$ECHO_URL/projects/$PROJECT_ID/knowledge/search" \
  -H "X-API-Key: $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "where do we validate a session token?", "top_k": 5 }'

You get back a ranked list of hits. Each hit carries a ref — an opaque string you resolve with fetch.

3. Resolve a hit

Take any ref from the search results and fetch its full content:

bash

curl -X POST "$ECHO_URL/projects/$PROJECT_ID/knowledge/fetch" \
  -H "X-API-Key: $SERVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ref": "code:github:acme/api:main:src/auth/verify.ts:verifySession" }'

The response is the full content object — the entity, its type, its relations in the graph, and the content itself.

4. Connect an agent via MCP

Wire Echo's MCP server into your editor so an agent can call the same operations. The MCP tool set is stable: the same tools work regardless of which sources are connected.

Next: Sources vs providers.