Quick Start: From Zero to Your First Vector Query

This walkthrough takes you from a brand-new FoxNose account to your first Flux API call. In ~10 minutes you will:

  1. Model a simple “Articles” collection in the dashboard.
  2. Publish an example article with vectorizable content.
  3. Expose the collection through a Flux API and mint a key.
  4. Call the Flux endpoint—first with a regular GET, then with a semantic (vector) search.
  5. Connect an AI agent to the same API over MCP.

No SDKs required; everything is done through the dashboard and simple HTTP requests.

Prerequisites

  • A FoxNose account (sign up at app.foxnose.net).
  • Access to the FoxNose dashboard (email verified).
  • A terminal with curl, a REST client such as Postman/Hoppscotch, or simply a browser tab for the GET requests.

When you sign up you’re prompted to create or join a workspace. Projects and environments are created as part of the onboarding flow in the next steps. The environment key (e.g., 7c9h4pwu) appears under the Environment menu in the sidebar when you open an environment in the dashboard.

Step 1 – Add Your First Collection

In FoxNose, a Collection is the top-level container for a collection of resources (similar to a content type or table). Each collection has its own schema and entries.

  1. After signing in, you’ll land in your default Personal organization. Click New Project.
    • Give the project a name (e.g., Demo Project).
    • When the project is created, FoxNose automatically provisions the first environment named Production.
  2. Click into the new environment to open the Database section.
  3. Click Add Collection. In the dialog:
    • Collection Name: Articles
    • Alias: articles (used in APIs)
  4. Once the collection appears in the list, click it to open the detail panel. We’ll add fields next.

Step 2 – Define Fields

  1. With the collection selected, open the Collection Schema tab.
  2. Click Create Version; FoxNose creates the initial schema version and opens it automatically.
  3. Switch to the Schema tab inside the version editor.
  4. Click Add Field to open the form and configure:
    • Field Name: Title
    • Key: title
    • Type: String
    • Required: enable the checkbox
    • Click Add Field at the bottom of the form to save.
  5. Repeat the process to add a summary field:
    • Field Name: Summary
    • Key: summary
    • Type: Text
    • Required: enabled
    • Vectorizable: enabled
    • Click Add Field to save.
  6. When both fields appear in the schema list, click Publish to finalize the schema. The version status changes from Draft to Published, which means you can start adding data right away.

Step 3 – Add Sample Content

  1. Return to the Database section and open the Articles collection.
  2. Switch to the Content tab inside the collection view.
  3. Click Add Resource to open the resource editor.
  4. Fill in the fields you defined in the schema for the first article:
    • Title: The Future of Electric Cars
    • Summary: Automakers are investing heavily in solid-state batteries and new charging networks to push EV adoption.
  5. Click Create and Publish to save the resource and mark it ready for delivery.
  6. Add a second resource for variety:
    • Click Add Resource again.
    • Title: Breakthroughs in Renewable Energy
    • Summary: Researchers are combining solar glass, grid storage, and offshore wind to stabilize renewable power supply across cities.
    • Click Create and Publish.

Step 4 – Create a Flux API and Connect the Collection

  1. Go to the Flux API section in the dashboard.
  2. Click Create API. In the dialog:
    • API Name: Demo API
    • URL Prefix: demo-api
    • Require API key authentication: leave unchecked for this quick start
    • Click Create API to save.
  3. After the API card appears, open it and switch to the Connected Collections tab, then click Connect Collection.
  4. In the dialog:
    • Select Collection: Articles
    • Access Methods: enable both List/Search Resources (get_many) and Get Individual Resources (get_one)
    • Leave Authentication as Public for this quick start
    • Click Connect Collection to save. The collection’s content is now accessible through the Flux endpoint.
  5. The collection now appears in the Connected Collections list. Click its name to view the auto-generated endpoints. You’ll see three cards (GET list, GET single, POST search). Click the row labeled GET /demo-api/articles—the full URL is copied to your clipboard.

Open a new browser tab, paste the copied URL (e.g., https://ENV_KEY.fxns.io/demo-api/articles), and press Enter. You should see the JSON listing of the two articles you created earlier. This confirms the collection is public and accessible.

Step 5 – Run a Vector (Semantic) Search

Remember how we marked the summary field as vectorizable? When you published the resources, FoxNose automatically generated embeddings for that field and stored them in a vector index. Semantic search is now available directly from the same GET endpoint—you just add query parameters.

Replace ENV_KEY with your actual Environment Key from the dashboard (Environment → Settings). Spaces in the query must be URL-encoded (%20) when using a browser.

curl "https://ENV_KEY.fxns.io/demo-api/articles\
?search_mode=vector\
&vector_search__query=advancements%20in%20electric%20vehicle%20batteries\
&vector_search__fields=summary\
&vector_search__top_k=10\
&vector_search__similarity_threshold=0.7"

Expected response (trimmed):

{
  "limit": 50,
  "results": [
    {
      "_sys": {
        "key": "dw2qC5qRwxuZ",
        "folder": "...",
        ...
      },
      "data": {
        "title": "The Future of Electric Cars",
        "summary": "Automakers are investing heavily..."
      }
    }
  ],
  "metadata": {
    "search_mode": "vector",
    "vector_search_enabled": true
  }
}

Even though the query never mentions “FoxNose” or the article title verbatim, Flux understands the semantic intent (“electric vehicle batteries”) and returns the relevant entry. Change vector_search__query to something like smart%20city%20renewable%20power—the second article (Breakthroughs in Renewable Energy) will surface because its summary discusses renewable infrastructure.

If you made the Flux API private, add an Authorization header per the authentication guide when calling the endpoint.

Step 6 – Connect Your Agent

The Flux API you just built is also an MCP server. Every Flux API exposes one at POST /{api_prefix}/_mcp, so an AI agent can list, fetch, and search your collections as native tools—no SDK wrapper, no glue code.

Point any Model Context Protocol client (Claude Desktop, Claude Code, Cursor, or another MCP-aware client) at the endpoint. The common config shape is:

{
  "mcpServers": {
    "foxnose-demo": {
      "type": "http",
      "url": "https://ENV_KEY.fxns.io/demo-api/_mcp"
    }
  }
}

The demo-api you built is public, so no headers are needed. For a private API, add an Authorization header inside a headers block—see Connect Claude for the exact shape. Clients that only speak stdio MCP need an HTTP bridge in between.

Before wiring it into a client, sanity-check the endpoint. Initialize a session, then list the tools:

URL=https://ENV_KEY.fxns.io/demo-api/_mcp

# 1. Initialize a session. Grab the Mcp-Session-Id from the response headers.
SID=$(curl -sS -i -X POST $URL \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | awk -F': ' 'tolower($1)=="mcp-session-id" {gsub(/\r/,"",$2); print $2}')

# 2. List the available tools.
curl -sS -X POST $URL \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

You should see five read tools: discover_resources, describe_resource, get_record, query_records, and search_records (plus write tools, if your key grants them). Your agent can now discover the Articles collection and run the same semantic search you just called by hand.

For the full walkthrough—wiring it into Claude Code, private-API auth, and per-API governance—see Connect Claude and Agent-Native Flux APIs.

Where to Go Next

You now have a working knowledge API with semantic search. Here's how to take it further:

Connect to Your AI Application

FoxNose is designed to be the knowledge layer for LLM applications. The Flux API you just created can power:

  • RAG pipelines — Retrieve relevant context for your LLM
  • AI agents — Give agents access to your knowledge base as a tool
  • Semantic search — Build intelligent search experiences

Check out our integration guides:

Explore More Features

Happy building!

Was this page helpful?